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

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