> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Collections

> Create, list, update, and delete collections

A collection is a container for agent runs, rubrics, and evaluation results.
See [Introduction](/introduction) for more on how collections fit into the Docent workflow.

## Create a Collection

```python theme={null}
from docent import Docent

client = Docent()

collection_id = client.create_collection(
    name="GPT-4 Customer Support Runs",
    description="Production runs from the support agent",
    metadata={"team": "support", "model": "gpt-4"},
)
print(collection_id)  # e.g., "a1b2c3d4-..."
```

### Parameters

<ParamField body="collection_id" type="str | None">
  Optional ID for the new collection. If not provided, one is generated automatically.
</ParamField>

<ParamField body="name" type="str | None">
  Display name for the collection.
</ParamField>

<ParamField body="description" type="str | None">
  Description of the collection's purpose.
</ParamField>

<ParamField body="metadata" type="dict | None">
  Arbitrary key-value metadata to attach to the collection.
</ParamField>

### Returns

<ResponseField name="collection_id" type="str">
  The ID of the created collection.
</ResponseField>

***

## List Collections

```python theme={null}
collections = client.list_collections()
for c in collections:
    print(f"{c['id']}: {c['name']} ({c['counts']['agent_run_count']} runs)")
```

### Returns

<ResponseField name="collections" type="list[dict]">
  List of collection summary objects, including ownership, your permission level, and precomputed counts.

  <Expandable title="Collection object fields">
    <ResponseField name="id" type="str">Collection ID.</ResponseField>
    <ResponseField name="name" type="str | None">Display name.</ResponseField>
    <ResponseField name="description" type="str | None">Description.</ResponseField>
    <ResponseField name="created_at" type="str">ISO timestamp of creation.</ResponseField>
    <ResponseField name="created_by" type="str">User ID of the creator.</ResponseField>

    <ResponseField name="owner" type="dict">
      Owner of the collection.

      <Expandable title="Owner fields">
        <ResponseField name="id" type="str">Owner user ID.</ResponseField>
        <ResponseField name="email" type="str">Owner email.</ResponseField>
        <ResponseField name="is_anonymous" type="bool">Whether the owner is an anonymous user.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="is_owner" type="bool">`True` if the requesting user owns the collection.</ResponseField>
    <ResponseField name="my_permission" type="str">Requesting user's permission level on the collection: `"read"`, `"write"`, or `"admin"`.</ResponseField>

    <ResponseField name="counts" type="dict">
      Precomputed counts for the collection.

      <Expandable title="Counts fields">
        <ResponseField name="agent_run_count" type="int">Number of agent runs in the collection.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Get a Collection

```python theme={null}
import requests

try:
    collection = client.get_collection("my-collection-id")
    print(collection["name"])
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("Collection not found")
    else:
        raise
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection to retrieve.
</ParamField>

### Returns

<ResponseField name="collection" type="dict">
  Collection details with ownership, your permission level, and precomputed counts.

  <Expandable title="Collection object fields">
    <ResponseField name="id" type="str">Collection ID.</ResponseField>
    <ResponseField name="name" type="str | None">Display name.</ResponseField>
    <ResponseField name="description" type="str | None">Description.</ResponseField>
    <ResponseField name="created_at" type="str">ISO timestamp of creation.</ResponseField>
    <ResponseField name="created_by" type="str">User ID of the creator.</ResponseField>

    <ResponseField name="owner" type="dict">
      Owner of the collection.

      <Expandable title="Owner fields">
        <ResponseField name="id" type="str">Owner user ID.</ResponseField>
        <ResponseField name="email" type="str">Owner email.</ResponseField>
        <ResponseField name="is_anonymous" type="bool">Whether the owner is an anonymous user.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="is_owner" type="bool">`True` if the requesting user owns the collection.</ResponseField>
    <ResponseField name="my_permission" type="str">Requesting user's permission level on the collection: `"read"`, `"write"`, or `"admin"`.</ResponseField>

    <ResponseField name="counts" type="dict">
      Precomputed counts for the collection.

      <Expandable title="Counts fields">
        <ResponseField name="agent_run_count" type="int">Number of agent runs in the collection.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The metadata blob is no longer included on this response. Use [`get_collection_metadata`](/sdk/collections/metadata) to retrieve it.
</Note>

### Errors

* **`HTTPError (404)`** — Collection not found

***

## Update a Collection

```python theme={null}
client.update_collection(
    "my-collection-id",
    name="Renamed Collection",
    description="Updated description",
)
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection to update.
</ParamField>

<ParamField body="name" type="str | None">
  New name. If `None`, the name is left unchanged.
</ParamField>

<ParamField body="description" type="str | None">
  New description. If `None`, the description is left unchanged.
</ParamField>

***

## Delete Agent Runs

Remove specific agent runs from a collection.

```python theme={null}
deleted = client.delete_agent_runs("my-collection-id", ["run-1", "run-2"])
print(f"Deleted {deleted} runs")
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="agent_run_ids" type="list[str]" required>
  List of agent run IDs to delete.
</ParamField>

### Returns

<ResponseField name="deleted_count" type="int">
  Number of agent runs deleted.
</ResponseField>

### Errors

* **`ValueError`** — `agent_run_ids` is empty
* **`HTTPError (404)`** — Collection not found