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

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

Returns

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

str
required
ID of the collection.

Returns

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

Select Agent Runs with DQL

Filter agent runs using DQL WHERE clauses.

Parameters

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

Returns

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

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

Returns

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:
str
required
ID of the collection.
str
required
ID of an existing saved filter.
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: