Skip to content

Workflow runs

Get workflow run

Read current run state with workspace read access. Request final output and files with `includeOutput`, or block outputs with `selectedOutputs`. Organization permission groups can hide output, files, or cost. A paused run lists every pause point in `paused.points`, with the fields a human pause asks for and its content with resolved secrets redacted; resume one with Resume workflow run. `includeFileBase64` inlines file bytes. A file or the total above 16 MiB returns `413` naming a download path; download large files individually. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. OAuth scope: `api:read`.

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

Read current run state with workspace read access. Request final output and files with includeOutput, or block outputs with selectedOutputs. Organization permission groups can hide output, files, or cost. A paused run lists every pause point in paused.points, with the fields a human pause asks for and its content with resolved secrets redacted; resume one with Resume workflow run.

includeFileBase64 inlines file bytes. A file or the total above 16 MiB returns 413 naming a download path; download large files individually. HEAD checks access with the same authorization as GET but skips side effects, returning an empty 200 without payload headers on success.

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
runIdstringRequired

Unique workflow run identifier.

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

Query parameters

includeOutputboolean

Include the final workflow output when true. It does not gate blockOutputs, which selectedOutputs selects on its own.

selectedOutputsstring

Comma-separated block output references to include, as blockId or blockId.path. Block names are not resolved here — unlike the execute request, this resource reads a recorded run and matches ids only, so a selector that is not headed by a block id answers 400 instead of an empty blockOutputs.

includeFileBase64boolean

Inline each produced file's bytes as base64. Requires includeOutput. A file above the inline ceiling answers 413 naming its download path; fetch large files from downloadPath instead.

base64MaxBytesinteger

Per-file inline ceiling, lowering but never raising the server limit of 16 MiB.

minimum
1
maximum
16777216

Responses

200

The workflow run status.

object

Detailed current state of a workflow run.

1 field
dataobjectRequired

Response data.

14 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 has a human or time pause that can still be resumed; once the run has finished and every pause point has resumed or failed, it reports the finished status. The single-run response provides the pause kind, resume time, and any automatic-resume waiting reason.

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

Trigger type that started the run. Backfilled as api for a run that is still queued, so it is populated from the first poll.

Schema details

Any of

Option 1string
Option 2null
startedAtvalueRequired

ISO 8601 start timestamp. A queued run reports the time it was enqueued, so it is populated from the first poll.

format
date-time
Schema details

Any of

Option 1string
Option 2null
endedAtvalueRequired

ISO 8601 end timestamp, or null while nonterminal.

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
versionvalueRequired

Deployment version the run executed. Null for a manual run, a queued run not yet started, or a run whose version no longer exists.

Schema details

Any of

Option 1integer
minimum
-9007199254740991
maximum
9007199254740991
Option 2null
pausedvalueRequired

Current pause details, or null when the run is not paused.

Schema details

Any of

Option 1object
9 fields
contextIdvalueRequired

Resume context identifier, or null while every pause point is mid-resume.

Schema details

Any of

Option 1string
Option 2null
pausedAtstringRequired

ISO 8601 timestamp when the execution entered the paused state.

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))$
resumeAtvalueRequired

ISO 8601 scheduled automatic-resume timestamp, or null when no resume time is set.

Schema details

Any of

Option 1string
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))$
Option 2null
pauseKindvalueRequired

Whether the pause waits for time or human input, or null when unspecified.

Schema details

Any of

Option 1string
enum
["time","human"]
Option 2null
blockedOnBlockIdvalueRequired

Workflow block awaiting resume, or null when no block is identified.

Schema details

Any of

Option 1string
Option 2null
automaticResumeWaitingReasonvalueRequired

Recorded automatic-resume failure, or null when no failure is recorded. Inspect pauseKind and resumeAt to distinguish a scheduled time pause from human input. Cleared after a successful resume. A non-retryable or exhausted failure starts with Automatic resume requires manual intervention: .

Schema details

Any of

Option 1string
Option 2null
pausePointCountnumberRequired

Number of pause points tracked for the execution.

resumedCountnumberRequired

Number of pause points that have resumed.

pointsarrayRequired

Every point the run is paused at, earliest first, at most 100; past 100, points not yet resumed are kept in preference to resumed ones. Resume one with Resume workflow run, naming its contextId and supplying input.

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 as the run executed it. Null only for a point paused before names were recorded whose run was manual or whose deployment 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.

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
errorvalueRequired

Structured execution failure, or null when none occurred. The failing block is read from the run trace, so blockId/blockName/blockType are absent, and a block-level failure reports EXECUTION_FAILED, when the trace is unavailable or hidden by organization permission groups.

Schema details

Any of

Option 1object

Structured in-band failure details for a workflow run.

5 fields
messagestringRequired

Human-readable workflow execution failure message.

codestringRequired

Stable machine-readable execution failure code. BLOCK_EXECUTION_FAILED and CHILD_WORKFLOW_FAILED are reported only where block attribution is available; elsewhere a block-level failure is reported as EXECUTION_FAILED.

enum
["TIMEOUT","CANCELLED","USAGE_LIMIT_EXCEEDED","INVALID_INPUT","BLOCK_EXECUTION_FAILED","CHILD_WORKFLOW_FAILED","EXECUTION_FAILED"]
blockIdstring

Identifier of the failing block, when attributable. Get workflow run reads it from the run trace, so it is absent there when the trace is unavailable or hidden by organization permission groups, when no failed block in the trace recorded the run error, and for a timeout, cancellation, usage-limit, or invalid-input failure.

blockNamestring

Display name of the failing block, when attributable. Present whenever blockId is.

blockTypestring

Integration or block type that failed, when attributable. Present whenever blockId is.

Additional properties are not allowed.

Option 2null
outputvalueRequired

Final output when includeOutput=true, or null when not requested or hidden by organization permission groups.

Schema details

Any of

Option 1value

Final workflow output value.

Option 2null
blockOutputsvalueRequired

Selected block outputs, or null when none were requested or execution data is hidden by organization permission groups. selectedOutputs controls these independently of includeOutput.

Schema details

Any of

Option 1object
Schema details
Additional propertiesvalue

Output value produced by one workflow block.

Option 2null
filesvalueRequired

Run-produced files when includeOutput=true, or null when not requested or execution data is hidden by organization permission groups.

Schema details

Any of

Option 1array
Schema details
Array itemobject

A file produced by a workflow run.

6 fields
idstringRequired

Identifier to address this file by on the download endpoint.

namestringRequired

File name, including its extension.

sizeintegerRequired

File size in bytes.

minimum
0
maximum
9007199254740991
typestringRequired

MIME type recorded for the file.

downloadPathstringRequired

Path to fetch this file's bytes from, relative to the API host.

base64valueRequired

Base64-encoded contents when includeFileBase64 was requested and the file fits the inline ceiling, otherwise null.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Option 2null

Additional properties are not allowed.

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,
    "version": 3,
    "paused": null,
    "cost": {
      "total": 12
    },
    "error": null,
    "output": {
      "result": "Ticket routed to Support"
    },
    "blockOutputs": null,
    "files": [
      {
        "id": "file_1a2b3c",
        "name": "summary.pdf",
        "size": 20480,
        "type": "application/pdf",
        "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a/files/file_1a2b3c",
        "base64": 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