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
ValueError—where_clauseis an empty string, orlimitis not positiveHTTPError— 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.

