Skip to main content
Agent runs represent execution traces of AI agents. See the Agent Run data model for the full schema.

​
Get a Single Agent Run

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

​
collection_id
str
required
ID of the collection containing the run.
​
agent_run_id
str
required
ID of the agent run to retrieve.

​
Returns

​
agent_run
AgentRun | None
The agent run object, or None if not found. Returns a fully validated AgentRun Pydantic model instance.

​
List All Agent Run IDs

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

​
Parameters

​
collection_id
str
required
ID of the collection.

​
Returns

​
agent_run_ids
list[str]
List of all agent run IDs in the collection.

​
Select Agent Runs with DQL

Filter agent runs using DQL WHERE clauses. 
# 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

​
collection_id
str
required
ID of the collection to query.
​
where_clause
str | None
DQL WHERE clause applied to the agent_runs table. Omit to return all runs.
​
limit
int | None
Maximum number of run IDs to return. Must be a positive integer.

​
Returns

​
agent_run_ids
list[str]
Agent run IDs matching the criteria.
If the query results are truncated (hit the server limit), a warning is logged. Use the limit parameter to control result size explicitly.

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

​
collection_id
str
required
ID of the collection containing the runs.
​
filter
dict
required
Filter definition to save. Use ["metadata", "field_name"] in key_path for agent-run metadata fields.
​
name
str | None
Optional display name for the saved filter.
​
description
str | None
Optional saved filter description.

​
Returns

​
saved_filter
dict
The saved filter response, including id, filter, and url.

​
Build a URL for an existing filter

If you already have a saved filter ID, build a shareable URL without creating a new filter: 
url = client.get_saved_filter_url("my-collection-id", "filter-id-123")
​
collection_id
str
required
ID of the collection.
​
filter_id
str
required
ID of an existing saved filter.
​
url
str
Shareable frontend URL that opens the collection’s agent-run table with the filter applied.

​
Common Patterns

​
Fetch Full Runs from IDs

# 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 directly: 
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)