Execute Workflow

Execute a deployment or use run.source: "manual" for the draft. Manual runs require personal or OAuth write access and reject async. Public deployments allow anonymous sync or streaming. Request application/x-ndjson for heartbeats and the final result. Timeouts return 200 with failed status and TIMEOUT. Supply X-Run-Id to prevent duplicate execution; reuse returns 409, never a replay. Input descriptions specify compatible modes; invalid combinations return 400.

OAuth scope: api:write.

POST/api/v2/workflows/{workflowId}/execute

Authorization

X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Path Parameters

workflowId*string

Unique workflow identifier.

Length1 <= length

Header Parameters

x-run-id?string

Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns 409 with RUN_ID_CONFLICT, without replaying results. Check Get Workflow Run, but 404 can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.

Match^[A-Za-z0-9._:-]+$

Length1 <= length <= 128

x-sim-via?string

Comma-separated workflow identifiers naming the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically; supply it yourself only when relaying an existing chain. A chain at the maximum depth is rejected with 409 and error.details.code: "CALL_CHAIN_DEPTH_EXCEEDED".

Request Body

application/json

Input, workflow-state selection, and execution-mode options. Input descriptions specify compatible modes; invalid combinations return 400.

TypeScript Definitions

Use the request body type in TypeScript.

input?

Workflow input keyed by the selected trigger input-field name.

run?|

Workflow state and entry point to execute. Omit for the active deployment. Manual execution requires OAuth or personal-key write access and supports synchronous or streamed runs only.

async?boolean

Queue the run and return a 202 receipt when true. Requires an OAuth access token or API key, cannot be combined with stream, and rejects all streaming and output-shaping options (selectedOutputs, includeThinking, includeToolCalls, includeFileBase64, base64MaxBytes).

Defaultfalse

executionTimeoutSeconds?integer

Maximum duration of an asynchronous run, in seconds, capped by the plan's execution timeout. Requires async: true; otherwise returns 400.

Range1 <= value <= 604800

stream?boolean

Return Server-Sent Events instead of JSON when true. Cannot be combined with async.

Defaultfalse

selectedOutputs?array<>

Output references for streaming: <blockName>.<outputPath> or <childWorkflowId>.<blockName>.<outputPath>, using normalized block names. Child references apply to every invocation. Requires stream: true and rejects synchronous or async requests. Use selectedOutputs with Get Workflow Run to narrow an existing run.

Itemsitems <= 100

includeThinking?boolean

Include model reasoning events in an agent-event stream. Requires stream: true and the X-Sim-Stream-Protocol: agent-events-v1 request header, and is rejected when async is true.

Defaultfalse

includeToolCalls?boolean

Include tool-call events in an agent-event stream. Requires stream: true and the X-Sim-Stream-Protocol: agent-events-v1 request header, and is rejected when async is true.

Defaultfalse

includeFileBase64?boolean

Inline eligible output files as base64 content. Rejected when async is true.

base64MaxBytes?integer

Maximum total bytes of file content to inline as base64, lowering but never raising the server limit of 16 MiB. Rejected when async is true.

Range0 < value <= 16777216

Response Body

`application/json`

curl -X POST "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute" \  -H "X-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "ticketId": "ticket_123"    }  }'

{
  "data": {
    "runId": "run_8f14e45f-ceea-467f-a",
    "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
    "status": "completed",
    "output": {
      "result": "Ticket routed to Support"
    },
    "error": null,
    "startedAt": "2026-08-09T18:04:10.000Z",
    "endedAt": "2026-08-09T18:04:11.000Z",
    "durationMs": 1000
  }
}

{
  "data": {
    "runId": "run_8f14e45f-ceea-467f-a",
    "statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Usage limit exceeded. Please upgrade your plan to continue."
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "Run ID has already been used",
    "details": {
      "code": "RUN_ID_CONFLICT",
      "runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
    }
  }
}

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}

{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Request body must be sent as application/json"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}

{
  "error": {
    "code": "CLIENT_CLOSED_REQUEST",
    "message": "Client cancelled request",
    "details": {
      "runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Execute Workflow

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

202application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

413application/json

415application/json

429application/json

499application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`