ReferenceAPI ReferenceworkflowsRuns

List Runs

List runs for a workflow, newest first by default. Returns a counted, paginated list of runs for the specified workflow. Each item includes the run's status, step progress (`total_steps`, `finished_steps`), credit usage, and the actor who triggered it. **Status filter:** Pass `?status=completed,failed` to OR-match multiple statuses. Values must be the raw lowercase RunStatus strings. Unknown values or empty tokens (e.g. `a,,b`) return 422. **Pagination:** `pagination.total` reflects the filtered count. Sort tiebreaks always append `id ASC` for stable offset/limit pagination. For aggregate statistics (pass rate, average duration) across all runs, use `GET /runs/summary` instead.

Authentication

AuthorizationBearer
Clerk JWT token
OR
AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Path parameters

workflow_idstringRequiredformat: "uuid"

Headers

X-Workspace-Idstring or nullOptional

Query parameters

offsetintegerOptional>=0Defaults to 0

Zero-based pagination offset.

limitintegerOptional1-100Defaults to 20

Maximum items to return (1–100).

statusstring or nullOptional

Comma-separated raw RunStatus values (e.g. completed,failed). Values are case-sensitive lowercase: pending, running, completed, failed, cancelled, paused. Multiple values OR-match. Empty tokens (e.g. a,,b) and unknown values return 422.

searchstring or nullOptional<=100 characters

Case-insensitive search over the triggering user’s display name (falls back to email).

sortenumOptionalDefaults to created_at

Sort field: created_at | started_at | completed_at | status. Defaults to created_at.

Allowed values:
orderenumOptionalDefaults to desc

asc or desc. Defaults to desc.

Allowed values:

Response

Successful Response
datalist of objects
metaobject
paginationobject
PaginationMeta variant for endpoints that compute an unpaginated total.

Errors

422
Unprocessable Entity Error