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

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

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.

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

  • ValueErrorwhere_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.

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

Use DQL Directly for Richer Queries

For queries beyond simple filtering, use DQL directly: