Skip to main content
GET
List Runs

Authorizations

Authorization
string
header
required

API key authentication. Get your API key from the Duvo dashboard.

Path Parameters

teamId
string
required

Query Parameters

limit
number
default:20

Number of runs per page (1-100, default 20)

Required range: 1 <= x <= 100
offset
number

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.

Required range: x >= 0
cursor
string

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.

Minimum string length: 1
include_total
enum<string>

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.

Available options:
true,
false
sort_by
enum<string>
default:created_at

Field to sort by (default created_at)

Available options:
created_at
sort_order
enum<string>
default:desc

Sort direction (default desc)

Available options:
asc,
desc
status
enum<string>

Filter to runs with this status

Available options:
not_started,
pending,
starting,
running,
waiting,
completed,
failed,
interrupted,
stopped,
needs_attention
agent_id
string<uuid>

Filter to runs for this agent

automation_id
string<uuid>

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

user_id
string<uuid>

Filter to runs owned by this user; non-superadmin callers are scoped to themselves regardless of this value

case_queue_id
string<uuid>

Filter to runs associated with this queue

source
string

Filter to runs created from this source (e.g. api, schedule)

Full-text search across run titles and case titles

has_issues
enum<string>

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.

Available options:
true,
false
issue_severity
enum<string>

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.

Available options:
critical,
medium,
low
since
string<date-time>

Return runs completed at or after this ISO-8601 timestamp. Runs that have not completed are excluded.

until
string<date-time>

Return runs completed before this ISO-8601 timestamp. The upper bound is exclusive. Runs that have not completed are excluded.

digest_id
string<uuid>
count_only
enum<string>
default:false

Skip row selection and enrichment. The normal list response shape is returned with an empty row array and the matching total.

Available options:
true,
false

Response

Default Response

data
object[]
required
total
number | null
required

Total runs matching the filters, ignoring pagination. Null when no count was requested (a cursor page without include_total=true, or include_total=false) — distinct from a count of 0.

has_more
boolean
default:false
required

Whether another page exists past this one, determined by looking one row ahead. False on a count_only response.

next_cursor
string | null
required

Pass as cursor (same filters, same sort_order) to fetch the next page. Null when has_more is false. Continues right after the last run on this page.