Skip to content
Try for free
On this page

Workflow runs

List workflow runs

List recorded workflow runs with workspace read access, filters, and cursor pagination. Cost can be hidden by organization permission groups. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. OAuth scope: `api:read`.

GET/api/v2/workflows/{workflowId}/runs

List recorded workflow runs with workspace read access, filters, and cursor pagination. Cost can be hidden by organization permission groups. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Path parameters

workflowIdstringRequired

Unique workflow identifier.

minLength
1

Query parameters

statusstring

Filter by run status.

enum
["pending","running","completed","failed","cancelled","paused"]
triggerstring

Filter by trigger type.

minLength
1
startDatestring

Only include runs started at or after this UTC ISO 8601 timestamp, e.g. 2026-08-06T00:00:00Z. A date without a time, or a timestamp carrying a UTC offset instead of Z, is rejected, as is year 0000, which names no storable instant.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
endDatestring

Only include runs started at or before this UTC ISO 8601 timestamp, e.g. 2026-08-06T00:00:00Z. A date without a time, or a timestamp carrying a UTC offset instead of Z, is rejected, as is year 0000, which names no storable instant.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
limitinteger

Maximum workflow runs to return per page. Must be a whole number from 1 to 100. Defaults to 50.

default
50
minimum
1
maximum
100
cursorstring

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

minLength
1
orderstring

Sort direction by run start time. This list is sortable only by run start time, so it takes order in place of sortBy/sortOrder, which it rejects.

default
desc
enum
["asc","desc"]

Responses

200

A page of workflow runs.

object

A cursor-paginated page of workflow run summaries.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

Summary of a recorded workflow run.

8 fields
runIdstringRequired

Unique workflow run identifier.

minLength
1
maxLength
128
pattern
^[A-Za-z0-9._:-]+$
workflowIdstringRequired

Workflow that produced the run.

statusstringRequired

Current or terminal run status. redacting is transient, reported while a finished run's output is being scrubbed. paused means the run is waiting at a human or time pause, or a resume attempt did not complete. The single-run response provides the pause kind, resume time, and any automatic-resume waiting reason.

enum
["pending","running","paused","redacting","completed","failed","cancelled"]
triggerstringRequired

Trigger type that started the run.

startedAtstringRequired

ISO 8601 timestamp when the run started.

format
date-time
endedAtvalueRequired

ISO 8601 timestamp when the run ended, or null while active.

format
date-time
Schema details

Any of

Option 1string
Option 2null
durationMsvalueRequired

Run duration in milliseconds, or null while active.

Schema details

Any of

Option 1number
Option 2null
costvalueRequired

Credits consumed, or null when unavailable or hidden by organization permission groups.

Schema details

Any of

Option 1object
1 field
totalnumberRequired

Total credits consumed by the run.

Additional properties are not allowed.

Option 2null

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response example 1

json
{
  "data": [
    {
      "runId": "run_8f14e45f-ceea-467f-a",
      "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
      "status": "completed",
      "trigger": "api",
      "startedAt": "2026-08-09T18:04:10.000Z",
      "endedAt": "2026-08-09T18:04:11.000Z",
      "durationMs": 1000,
      "cost": {
        "total": 12
      }
    }
  ],
  "nextCursor": null
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit