Run a workflow — Era documentation

Runs a deployed workflow from outside: waiting for the result, in the background, or streamed.

POSThttps://app.getera.io/api/workflows/{id}/execute

API key

Starts a workflow from another system. Called with an API key, it always runs the deployed version of the workflow; draft changes have no effect.

Authentication

An API key in the x-api-key header. The key must belong to the workflow's workspace and its owner must be allowed to see the workflow. See Authentication.

Path parameter

Name	Type	Required	Description
`id`	string	Yes	The workflow's id. It is in the editor's address bar: `/workspace/<workspace>/workflows/<id>`.

Body

The JSON body becomes the workflow's input as is. The expected fields are listed under inputs in the Get a workflow response. The fields below are not passed as input; they control the run:

Name	Type	Required	Description
`selectedOutputs`	string array	No	Return only these block outputs.
`stream`	boolean	No	When `true`, the response is a Server-Sent Events stream.
`includeFileBase64`	boolean	No	Include files in the output as base64. Default `true`.
`base64MaxBytes`	integer	No	Upper bound (bytes) for files included as base64.

Headers

Header	Value	Effect
`X-Execution-Mode`	`async`	The run is queued and `202` comes back at once. Fetch the result with Background job status.
`X-Stream-Response`	`true`	Same as `stream: true`.

Example

curl -X POST https://app.getera.io/api/workflows/wf_demo123/execute \
  -H "x-api-key: ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customerName": "Demo Cafe", "amount": 1200}'

Response (waiting)

{
  "success": true,
  "executionId": "5d7e2a10-0000-4000-8000-000000000020",
  "output": { "content": "Quote prepared." },
  "metadata": {
    "duration": 2140,
    "startTime": "2026-10-14T09:30:00.000Z",
    "endTime": "2026-10-14T09:30:02.140Z"
  }
}

If the workflow has a Response block, the HTTP response that block defines (status, headers, body) comes back directly.

Response (background)

With X-Execution-Mode: async:

{
  "success": true,
  "async": true,
  "jobId": "job_7f3c",
  "executionId": "5d7e2a10-0000-4000-8000-000000000020",
  "message": "Workflow execution queued",
  "statusUrl": "https://app.getera.io/api/jobs/job_7f3c"
}

Status 202.

Errors

Status	When
`400`	The body does not match the schema: `{"error": "Invalid request body", "details": [...]}`.
`401`	Missing or invalid key.
`402`	Usage limit reached.
`403`	The workflow is not deployed, or no access.
`404`	No such workflow, or automations are switched off in this workspace.
`408`	The run timed out; the body has the `output` so far and an `error`.
`409`	Workflows are calling each other in a loop.
`429`	Run rate limit reached.
`500`	The run failed: `{"success": false, "error": "..."}`.

Limits

Runs and usage are limited by your subscription. The current values are in the limits field of the List workflows response. See also Usage.