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

# Query Agent Runs

> Retrieve and search agent runs in a collection

Agent runs represent execution traces of AI agents. See the
[Agent Run data model](/concepts/agent-run) for the full schema.

## Get a Single Agent Run

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

client = Docent()

run = client.get_agent_run("my-collection-id", "run-id-123")
if run:
    for transcript in run.transcripts:
        for msg in transcript.messages:
            print(f"{msg.role}: {msg.content[:100]}")
```

### Parameters

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

<ParamField body="agent_run_id" type="str" required>
  ID of the agent run to retrieve.
</ParamField>

### Returns

<ResponseField name="agent_run" type="AgentRun | None">
  The agent run object, or `None` if not found. Returns a fully validated
  `AgentRun` Pydantic model instance.
</ResponseField>

***

## List All Agent Run IDs

```python theme={null}
run_ids = client.list_agent_run_ids("my-collection-id")
print(f"Collection has {len(run_ids)} runs")
```

### Parameters

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

### Returns

<ResponseField name="agent_run_ids" type="list[str]">
  List of all agent run IDs in the collection.
</ResponseField>

***

## Select Agent Runs with DQL

Filter agent runs using [DQL](/analysis/dql) WHERE clauses.

```python theme={null}
# Get runs where model is "gpt-4"
run_ids = client.select_agent_run_ids(
    "my-collection-id",
    where_clause="metadata_json->>'model' = 'gpt-4'",
    limit=100,
)
print(f"Found {len(run_ids)} matching runs")
```

### Parameters

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

<ParamField body="where_clause" type="str | None">
  DQL WHERE clause applied to the `agent_runs` table. Omit to return all runs.
</ParamField>

<ParamField body="limit" type="int | None">
  Maximum number of run IDs to return. Must be a positive integer.
</ParamField>

### Returns

<ResponseField name="agent_run_ids" type="list[str]">
  Agent run IDs matching the criteria.
</ResponseField>

<Note>
  If the query results are truncated (hit the server limit), a warning is logged.
  Use the `limit` parameter to control result size explicitly.
</Note>

### Errors

* **`ValueError`** — `where_clause` is an empty string, or `limit` is not positive
* **`HTTPError`** — Invalid DQL syntax or collection not found

***

## Share a Saved Filter

Create a saved filter and get a URL that opens the collection's agent-run table
with that filter applied.

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

client = Docent()

job_id = "benchmark-job-123"
saved_filter = client.create_saved_filter(
    "my-collection-id",
    {
        "type": "complex",
        "op": "and",
        "filters": [
            {
                "type": "primitive",
                "key_path": ["metadata", "job_id"],
                "op": "==",
                "value": job_id,
            }
        ],
    },
    name=f"job_id={job_id}",
)

print(saved_filter["url"])
```

### Parameters

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

<ParamField body="filter" type="dict" required>
  Filter definition to save. Use `["metadata", "field_name"]` in `key_path` for
  agent-run metadata fields.
</ParamField>

<ParamField body="name" type="str | None">
  Optional display name for the saved filter.
</ParamField>

<ParamField body="description" type="str | None">
  Optional saved filter description.
</ParamField>

### Returns

<ResponseField name="saved_filter" type="dict">
  The saved filter response, including `id`, `filter`, and `url`.
</ResponseField>

### Build a URL for an existing filter

If you already have a saved filter ID, build a shareable URL without creating a
new filter:

```python theme={null}
url = client.get_saved_filter_url("my-collection-id", "filter-id-123")
```

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

<ParamField body="filter_id" type="str" required>
  ID of an existing saved filter.
</ParamField>

<ResponseField name="url" type="str">
  Shareable frontend URL that opens the collection's agent-run table with the
  filter applied.
</ResponseField>

***

## Common Patterns

### Fetch Full Runs from IDs

```python theme={null}
# Get IDs first, then fetch full runs
run_ids = client.select_agent_run_ids(
    "my-collection-id",
    where_clause="metadata_json->>'status' = 'failed'",
    limit=10,
)

runs = [client.get_agent_run("my-collection-id", rid) for rid in run_ids]
```

### Use DQL Directly for Richer Queries

For queries beyond simple filtering, use [DQL](/sdk/dql/execute) directly:

```python theme={null}
result = client.execute_dql(
    "my-collection-id",
    """
    SELECT id, metadata_json->>'model' AS model, metadata_json->>'score' AS score
    FROM agent_runs
    WHERE CAST(metadata_json->>'score' AS DOUBLE PRECISION) > 0.8
    ORDER BY CAST(metadata_json->>'score' AS DOUBLE PRECISION) DESC
    LIMIT 20
    """
)
rows = client.dql_result_to_dicts(result)
```