Skip to content
Try for free
On this page

Workflow runs

List paused workflow runs

List a workspace's runs waiting on human input, with workspace read access. Each run lists the human pause points it still waits at, exactly as Get workflow run shows them; resume one with Resume workflow run. Request each point's reviewer content with `includeOutput`. Organization permission groups can hide pause fields. A page ends early, with a cursor, once it holds 100 pause points. OAuth scope: `api:read`.

GET/api/v2/workflows/runs/paused

List a workspace's runs waiting on human input, with workspace read access. Each run lists the human pause points it still waits at, exactly as Get workflow run shows them; resume one with Resume workflow run. Request each point's reviewer content with includeOutput. Organization permission groups can hide pause fields. A page ends early, with a cursor, once it holds 100 pause points.

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.

Query parameters

workspaceIdstringRequired

Workspace whose paused runs should be listed.

minLength
1
maxLength
128
includeOutputboolean

Include each pause point's reviewer display content when true.

limitinteger

Maximum runs to return per page. A page also ends early once it holds 100 pause points, so it can return fewer runs while nextCursor is set. Must be a whole number from 1 to 25. Defaults to 10.

default
10
minimum
1
maximum
25
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
sortBystring

Field used to sort the result.

default
pausedAt
enum
["pausedAt"]
sortOrderstring

Sort direction.

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

Responses

200

A page of paused workflow runs.

object

A cursor-paginated page of runs waiting on human input.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

A run waiting on human input, with the points it waits at.

5 fields
runIdstringRequired

Unique workflow run identifier.

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

Workflow that produced the run.

workflowNamestringRequired

Name of the workflow that produced the run.

pausedAtstringRequired

ISO 8601 timestamp when the run entered the paused state.

format
date-time
pointsarrayRequired

Human pause points still waiting for a resume, earliest first, at most 100. Resume one with Resume workflow run, naming its contextId and supplying input. Get workflow run lists every point of the run, including time pauses and points already resuming.

Schema details
Array itemobject

One point at which a paused run waits.

12 fields
contextIdstringRequired

Pause context to name in contextId when resuming this point.

blockIdstringRequired

Workflow block that paused.

blockNamevalueRequired

Name of the block in the deployment version the run executed, or null for a manual run or when the version no longer exists.

Schema details

Any of

Option 1string
Option 2null
kindstringRequired

human waits for a resume request; time resumes automatically at resumeAt.

enum
["human","time"]
statusstringRequired

Resume state of this point: waiting, queued behind another resume, resuming, resumed, or a failed resume attempt.

enum
["paused","queued","resuming","resumed","failed"]
registeredAtvalueRequired

ISO 8601 timestamp when the run paused at this point, or null for a point recorded without one.

format
date-time
Schema details

Any of

Option 1string
Option 2null
resumeAtvalueRequired

ISO 8601 automatic-resume timestamp for a time pause, otherwise null.

format
date-time
Schema details

Any of

Option 1string
Option 2null
parallelvalueRequired

Parallel branch of the pause, or null outside a parallel.

Schema details

Any of

Option 1object
3 fields
parallelIdstringRequired

Parallel block containing the pause.

branchIndexintegerRequired

Zero-based branch that paused.

minimum
-9007199254740991
maximum
9007199254740991
branchTotalvalueRequired

Number of branches, or null when unrecorded.

Schema details

Any of

Option 1integer
minimum
-9007199254740991
maximum
9007199254740991
Option 2null

Additional properties are not allowed.

Option 2null
loopvalueRequired

Loop iteration of the pause, or null outside a loop.

Schema details

Any of

Option 1object
2 fields
loopIdstringRequired

Loop block containing the pause.

iterationintegerRequired

Zero-based iteration that paused.

minimum
-9007199254740991
maximum
9007199254740991

Additional properties are not allowed.

Option 2null
inputFieldsvalueRequired

Fields a human pause asks for, without default values. Labels and descriptions are resolved, so they are withheld when organization permission groups hide execution data. Null then, for a time pause, a pause with no declared form, fields over 64 KiB or not provably free of secrets, or one recorded before pause details were captured.

Schema details

Any of

Option 1array
Schema details
Array itemobject

One field a human pause asks the resumer to fill.

7 fields
namestringRequired

Key to supply this field under in the resume input.

labelstringRequired

Display label for the field.

typestringRequired

Declared value type, such as string, number, or boolean.

descriptionstring

Field help text, when configured.

placeholderstring

Placeholder text, when configured.

requiredbooleanRequired

Whether the field is marked required.

optionsarray

Selectable options, when the field offers a fixed set.

Schema details
Array itemvalue

One selectable option.

Additional properties are not allowed.

Option 2null
displayvalueRequired

Content the pause presents to its reviewer, with the run's resolved secrets redacted. Null unless includeOutput=true, when hidden by organization permission groups, for a time pause, for content over 64 KiB or not provably free of secrets, or for a pause recorded before pause details were captured.

Schema details

Any of

Option 1value

Reviewer content value.

Option 2null
queuePositionvalueRequired

Position among pending resume requests for this run, or null when none waits.

Schema details

Any of

Option 1integer
minimum
-9007199254740991
maximum
9007199254740991
Option 2null

Additional properties are not allowed.

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",
      "workflowName": "Customer support triage",
      "pausedAt": "2026-08-09T18:04:11.000Z",
      "points": [
        {
          "contextId": "blk_approval",
          "blockId": "blk_approval",
          "blockName": "Manager approval",
          "kind": "human",
          "status": "paused",
          "registeredAt": "2026-08-09T18:04:11.000Z",
          "resumeAt": null,
          "parallel": null,
          "loop": null,
          "inputFields": [
            {
              "name": "approved",
              "label": "Approved",
              "type": "boolean",
              "required": true
            }
          ],
          "display": null,
          "queuePosition": null
        }
      ]
    }
  ],
  "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