Running Workflows

Asynchronously (POST /run)

Enqueues the workflow and returns immediately with a job object. The job is processed in the background.

POST /workflows/42/run
Authorization: Bearer <token>
Content-Type: application/json

{}

Response — the job is created with status: "pending":

{
  "success": true,
  "data": {
    "id": 123,
    "slug": "job-my-search-workflow-1712345678901",
    "status": "pending",
    "workflowId": 42,
    ...
  }
}

Use GET /workflows/42/latest-job or GET /workflows/42/jobs to poll for completion and retrieve results.

Overriding the Graph at Runtime

Pass nodes and/or edges to override the stored graph for a single execution without modifying the saved workflow:

POST /workflows/42/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "nodes": [ ... ],
  "edges": [ ... ]
}

---

Synchronously (POST /run-sync)

Enqueues the workflow and blocks until the job completes or times out. The response contains the full job with all node outputs populated.

POST /workflows/42/run-sync
Authorization: Bearer <token>
Content-Type: application/json

{
  "timeout": 120
}

Request Body

Field	Type	Default	Max	Description
nodes	array?	stored nodes	—	Override the workflow's nodes for this execution
edges	array?	stored edges	—	Override the workflow's edges for this execution
timeout	number?	300	600	Seconds to wait before returning a timeout error

Response — Success

The job is returned with status: "completed" and all node outputs populated:

{
  "success": true,
  "data": {
    "id": 123,
    "slug": "job-my-search-workflow-1712345678901",
    "status": "completed",
    "nodes": [
      {
        "id": "fetchEntries",
        "data": {
          "isExecuted": true,
          "outputs": [
            { "id": 1, "title": "Introduction to embeddings", ... },
            { "id": 2, "title": "Semantic search at scale", ... }
          ],
          "errors": []
        },
        ...
      }
    ],
    ...
  }
}

Response — Timeout (HTTP 408)

If the job does not complete within the timeout window, a 408 Request Timeout is returned. The job continues running in the background.

{
  "success": false,
  "message": "Job execution timeout: the job is still running but exceeded the wait time.",
  "data": {
    "job_id": 123,
    "slug": "job-my-search-workflow-1712345678901",
    "status": "pending",
    "timeout": 120,
    "elapsed_seconds": 120
  }
}

You can retrieve the final result later using GET /workflows/42/latest-job once the job finishes.

Response — Failure

If the job fails, it is returned with status: "failed". Errors are attached to the specific node that failed in data.errors.

---

Choosing Between run and run-sync

	run	run-sync
Returns	Immediately	After job completes (or timeout)
Response contains	Job ID and initial status	Full job with all outputs
Use when	You don't need the result inline	You need the output in the same request
Max wait	—	600 seconds