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

***

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