> ## 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']}")
```

### Returns

<ResponseField name="collections" type="list[dict]">
  List of collection objects.

  <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>
  </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">
  The collection object with `id`, `name`, `description`, `created_at`, and `created_by`.
</ResponseField>

### 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>

***

## Check if a Collection Exists

```python theme={null}
if client.collection_exists("my-collection-id"):
    print("Collection found")
```

### Parameters

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

### Returns

<ResponseField name="exists" type="bool">
  `True` if the collection exists, `False` otherwise.
</ResponseField>

***

## 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