List Runs
listRunsRead-onlyIdempotent
List runs for the current team. Supports filtering by agent, user, queue, status, etc. Messages, evaluation data, and queue metadata are included where available. Set count_only=true to skip Run row selection and enrichment. The normal response shape is returned with data: [] and the matching total. To sweep a whole team, follow next_cursor rather than raising offset.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of runs per page (1-100, default 20) | |
| since | No | Return runs completed at or after this ISO-8601 timestamp. Runs that have not completed are excluded. | |
| until | No | Return runs completed before this ISO-8601 timestamp. The upper bound is exclusive. Runs that have not completed are excluded. | |
| cursor | No | Resume after the run a previous page ended on: pass the `next_cursor` that page returned, with the same filters and sort_order. Unlike offset, a cursor page does not re-read the runs before it, so a sweep does not slow down as it goes deeper; send `include_total=false` on the first page to skip the full count too. Runs created in between cannot shift a boundary already passed, so pages do not repeat or skip runs the way offset pages do. A run created or completed while a sweep is in progress can still be missed by that sweep, so to export runs continuously, poll with `since` and a short overlap and deduplicate on run id. Cannot be combined with `offset`. 400 when the value is not a valid runs cursor. | |
| offset | No | Number of runs to skip. Every skipped run is still read by the database, so deep offsets get slower page by page; to walk a whole team's history, page with `cursor` instead. | |
| search | No | Full-text search across run titles and case titles | |
| source | No | Filter to runs created from this source (e.g. api, schedule) | |
| status | No | Filter to runs with this status | |
| sort_by | No | Field to sort by (default created_at) | created_at |
| team_id | No | Duvo team UUID to operate on. API keys are pinned to a single team — omit this (it falls back to the key's team) or pass that same team; a different team is rejected. OAuth callers, who can span multiple teams, should pass the target team here. | |
| user_id | No | Filter to runs owned by this user. Callers below Administrator, other than Lead Builders, are scoped to themselves regardless of this value, unless the request comes from a dashboard | |
| agent_id | No | Filter to runs for this agent | |
| digest_id | No | ||
| count_only | No | Skip row selection and enrichment. The normal list response shape is returned with an empty row array and the matching total. | false |
| has_issues | No | Filter on the run's latest successful evaluation: true returns only runs it flagged, false only runs it did not. Only the latest evaluation counts — an older flag does not match — and a run whose latest evaluation errored, or that has none, counts as unflagged. Omit to return both. | |
| sort_order | No | Sort direction (default desc) | desc |
| automation_id | No | Filter to runs that ran under this automation. A run keeps the automation it was created under, even after its agent moves to another automation | |
| case_queue_id | No | Filter to runs associated with this queue | |
| include_total | No | Whether to return `total`, the count of every matching run. Counting walks every match, so it costs far more than the page itself on a large team. Defaults to true on a first page and false on a `cursor` page, where `total` is null unless this is true. Implied by `count_only`. | |
| issue_severity | No | If set, only return runs whose latest successful evaluation has at least one failing rubric with this severity (critical | medium | low). Implies has_issues; legacy evaluations without severity companion fields do not match this filter. |