Skip to main content
POST
List runs

Authorizations

Authorization
string
header
required

API token from cargo-ai login. Send as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was.

Maximum string length: 255
Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Body

application/json

Request body schema.

workflowUuid
string<uuid>

Workflow identifier. Omitted lists the runs of every play and tool, which requires a created window of at most 30 days.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
userUuid
string<uuid>

User identifier to filter by.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
releaseUuid
string<uuid>

Release identifier to filter by.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
batchUuid
string<uuid>

Batch identifier to filter by.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
statuses
enum<string>[]

Run statuses to include.

Available options:
idle,
pending,
running,
success,
error,
cancelling,
cancelled,
skipped
recordId
string

Record ID to filter by.

recordTitle
string

Record title to filter by.

recordTitleOrId
string

Record title or ID to filter by.

Case-insensitive partial match on record title or record ID.

Minimum string length: 1
isFinished
boolean

Whether to only select finished runs.

parentBatchUuid
string<uuid>

Parent batch identifier to filter by.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
parentUuid
string<uuid>

Parent run identifier to filter by.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
parentNodeUuid
string<uuid>

Parent node identifier to filter by.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
isGroupParent
boolean

Whether to select group parent runs.

executionsFilter
Executions filter · object

Execution filters for matching runs.

createdAfter
string

Include runs created after this timestamp. Required when the workflow identifier is omitted.

createdBefore
string

Include runs created before this timestamp.

updatedAfter
string

Include runs updated after this timestamp.

updatedBefore
string

Include runs updated before this timestamp.

limit
number

Maximum number of runs to return.

offset
number

Number of runs to skip.

Response

List runs

runs
Runs · object[]
required

Runs matching the filter.

count
number
required

Total count of matching runs.