Skip to navigation
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