Run Workflow (Async)

POST /api/v1/workflows/:workflowId/run-async — start a workflow run and poll for the result.

Starts the currently-deployed version of a published workflow and returns immediately with the run's id, instead of blocking like /run. Use this for anything that might take longer than a few seconds, and always for a workflow that can pause on human review.

POST /api/v1/workflows/{workflowId}/run-async

Path parameters

Parameter	Type	Description
`workflowId`	string (UUID)	The workflow to run.

Request body

Identical to /run: an optional input object, defaulting to {}.

Response

202 Accepted

{
  "executionId": "8f2a1c9e-...",
  "workflowId": "3f9c1a2e-...",
  "status": "queued",
  "createdAt": 1732550123
}

The response is returned as soon as the run record exists — dispatch to the workflow engine happens in the background. A run that could not be dispatched is closed as failed with a reason you'll see when you poll it, rather than being left stuck at queued.

Lifecycle

POST /workflows/:workflowId/run-async → receive an executionId, status queued.
GET /workflow-jobs/:executionId (poll) → status moves through queued → running → a terminal state, possibly pausing at awaiting_approval or waiting on the way.
Optionally, POST /workflow-jobs/:executionId/cancel at any point while it is still in flight.

In-flight status	Meaning
`queued`	Accepted, not yet picked up.
`running`	Executing.
`paused`	Suspended.
`awaiting_approval`	Waiting on a person — see Human review.
`waiting`	Parked on a Wait node's timer. `error` carries `Waiting until <time> (<zone>)`, read in that node's time zone. The only in-flight status that does not count against your concurrency ceiling.

Terminal status	Meaning
`completed`	Finished successfully.
`failed`	A node errored, or a node never became reachable.
`loop_limit_reached`	A Loop node hit its iteration ceiling. Not a failure.
`policy_blocked`	A budget or policy cap rejected the run pre-flight. Not a failure.
`cancelled`	Cancelled before it finished.
`concurrency_limit_reached`	Rejected pre-flight at the concurrent-run ceiling.

The run id is the execution id

There is no separate job identifier. executionId is the run's one id everywhere — in these responses, in Studio's Activity tab, and in the trace view. The polling endpoints live under /workflow-jobs/ (not /jobs/, which belongs to agent async jobs), but the id they take is this executionId.

Recommended polling interval

Poll every 2 seconds for the first 30 seconds.
After 30 seconds, back off to every 5 seconds.
If the run reaches awaiting_approval, back off much further — a review window is measured in hours or days, not seconds — or stop polling and cancel.
If it reaches waiting, read the resume instant out of error and poll again after it rather than on an interval: a wait can be as long as 365 days.
Don't poll more than once per second; it burns your rate limit for no benefit.

Python example

import asyncio
import httpx

TERMINAL = {
    "completed", "failed", "loop_limit_reached",
    "policy_blocked", "cancelled", "concurrency_limit_reached",
}

async def run_and_poll(workflow_id: str, payload: dict, api_key: str) -> dict:
    base = "https://api.elizon.ai/api/v1"
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}

    async with httpx.AsyncClient() as client:
        r = await client.post(f"{base}/workflows/{workflow_id}/run-async",
                              headers=headers, json={"input": payload})
        execution_id = r.json()["executionId"]

        interval, elapsed = 2, 0
        while True:
            await asyncio.sleep(interval)
            elapsed += interval
            if elapsed > 30:
                interval = 5
            r = await client.get(f"{base}/workflow-jobs/{execution_id}", headers=headers)
            run = r.json()
            if run["status"] == "awaiting_approval":
                interval = 300          # a person has to answer; stop hammering
            if run["status"] in TERMINAL:
                return run

Errors

Identical to /run, minus the timeout — this endpoint never blocks, so it returns no 504.

Status	`error`	When
`400`	validation error	The request body fails validation, or holds more than 20,000 values (array elements plus object keys across the whole body, each array or object counting 5 more) or nests deeper than 256 levels
`403`	`forbidden`	The workflow belongs to a different project than your project-scoped key
`404`	`workflow_not_found`	No such workflow in your organization
`409`	`workflow_not_published`	The workflow has no active deployment
`429`	`concurrency_limit_reached`	Your organization is at its concurrent-run ceiling
`500`	`execution_create_failed`	The run record could not be created

Example

curl -X POST https://api.elizon.ai/api/v1/workflows/{workflowId}/run-async \
  -H "X-API-Key: elz_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input": {"orderId": "A-1001"}}'

Run Workflow (Async)

On this page