Skip to content
Try for free
On this page

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. `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.

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.

13 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","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
pausedvalueRequired

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

Schema details

Any of

Option 1object
8 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.

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. Reclassified from the persisted error message, so blockId/blockName/blockType are absent and a block-level failure reports EXECUTION_FAILED here even when the same run reported BLOCK_EXECUTION_FAILED on its synchronous execute response.

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. Present on the synchronous execute response only; the polled run resource and the resume response cannot attribute a block.

blockNamestring

Display name of the failing block. Present on the synchronous execute response only.

blockTypestring

Integration or block type that failed. Present on the synchronous execute response only.

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,
    "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