Execute Workflow

Execute a deployed workflow synchronously, asynchronously, or as Server-Sent Events. Public workflows permit anonymous synchronous and streaming execution; asynchronous execution requires an API key. A synchronous run that exceeds its execution timeout returns HTTP 200 with status: "failed" and error.code: "TIMEOUT" rather than an HTTP error, so branch on status. The optional X-Run-Id header is a one-shot uniqueness claim, not an idempotency key: reusing a value returns 409 with error.details.code: "RUN_ID_CONFLICT" and never replays the earlier run. Option constraints — each is a 400: (1) async: true requires an API key; anonymous public-workflow callers may only execute synchronously or as a stream. (2) async and stream cannot both be true. (3) executionTimeoutSeconds is accepted only when async: true. (4) async: true rejects every streaming and output-shaping option — selectedOutputs, includeThinking, includeToolCalls, includeFileBase64, and base64MaxBytes. (5) includeThinking and includeToolCalls require stream: true. (6) includeThinking and includeToolCalls require the X-Sim-Stream-Protocol: agent-events-v1 request header, which declares that the client understands agent-event frames.

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

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one from the Sim dashboard under Settings > API Keys. A workspace API key is not accepted everywhere: operations that act on behalf of a specific human — administrative reads, secret access, and irreversible or governance-affecting writes — always reject it, whatever role the key carries. Each such operation says so in its own description, and the rejection surfaces as 403 unless the operation conceals unauthorized resources, in which case it is reported as 404. Use a personal API key for those.

In: header

Path Parameters

id*string

Unique workflow identifier.

Length1 <= length

Header Parameters

x-run-id?string

Caller-supplied run identifier, available only to API-key callers. This is a one-shot uniqueness claim, NOT an idempotency key: the first request to use a value starts a run, and any later request reusing it fails with 409 and error.details.code: "RUN_ID_CONFLICT" instead of replaying the original result. To retry safely, generate a fresh value per attempt and reconcile duplicates yourself, or omit the header and let the server allocate the run identifier.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
x-sim-via?string

Comma-separated workflow identifiers describing the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically when one workflow calls another; supply it yourself only when relaying an existing chain. A chain already at the maximum depth is rejected with 409 and error.details.code: "CALL_CHAIN_DEPTH_EXCEEDED", which is how runaway recursion between workflows is stopped.

Request Body

application/json

Input and execution-mode options for a deployed workflow. Option constraints — each is a 400: (1) async: true requires an API key; anonymous public-workflow callers may only execute synchronously or as a stream. (2) async and stream cannot both be true. (3) executionTimeoutSeconds is accepted only when async: true. (4) async: true rejects every streaming and output-shaping option — selectedOutputs, includeThinking, includeToolCalls, includeFileBase64, and base64MaxBytes. (5) includeThinking and includeToolCalls require stream: true. (6) includeThinking and includeToolCalls require the X-Sim-Stream-Protocol: agent-events-v1 request header, which declares that the client understands agent-event frames.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute" \  -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": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}