Executions

Monitor and control workflow executions. Each execution represents a single run of a workflow, including its status, progress, node-level spans, and logs.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Execution Object

{
  "id": "exec_xyz789",
  "workflowId": "wf_abc123",
  "status": "completed",
  "startedAt": "2025-02-01T14:22:00Z",
  "endedAt": "2025-02-01T14:25:30Z",
  "durationMs": 210000,
  "trigger": {
    "type": "manual",
    "data": {}
  },
  "triggerType": "manual",
  "userId": "user_456",
  "organizationId": "org_xyz",
  "config": {},
  "error": null,
  "progress": 100,
  "createdAt": "2025-02-01T14:22:00Z",
  "updatedAt": "2025-02-01T14:25:30Z"
}

Span Object

{
  "id": "span_001",
  "executionId": "exec_xyz789",
  "nodeId": "node_1",
  "nodeLabel": "Extract Orders",
  "nodeType": "mysql-source",
  "status": "completed",
  "startedAt": "2025-02-01T14:22:01Z",
  "endedAt": "2025-02-01T14:22:45Z",
  "durationMs": 44000,
  "inputData": {},
  "outputData": {
    "rowCount": 1500
  },
  "error": null
}

Log Object

{
  "id": "log_001",
  "executionId": "exec_xyz789",
  "level": "info",
  "message": "Successfully extracted 1500 rows from orders table",
  "nodeId": "node_1",
  "createdAt": "2025-02-01T14:22:45Z"
}

---

GET /api/v1/executions

List executions with optional filtering.

Scope: workflows:read

Query Parameters

Parameter	Type	Required	Description
workflow_id	string	No	Filter by workflow ID
status	string	No	Filter by status: pending, running, completed, failed, stopped
trigger_type	string	No	Filter by trigger type: manual, schedule, webhook, api
since	string	No	ISO 8601 datetime. Return executions started after this time
until	string	No	ISO 8601 datetime. Return executions started before this time
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)
sort	string	No	Sort field and direction, e.g. startedAt:desc

Response 200 OK

{
  "count": 156,
  "limit": 20,
  "offset": 0,
  "executions": [
    {
      "id": "exec_xyz789",
      "workflowId": "wf_abc123",
      "status": "completed",
      "startedAt": "2025-02-01T14:22:00Z",
      "endedAt": "2025-02-01T14:25:30Z",
      "durationMs": 210000,
      "triggerType": "manual",
      "userId": "user_456",
      "progress": 100,
      "createdAt": "2025-02-01T14:22:00Z"
    }
  ]
}

---

GET /api/v1/executions/:id

Get a single execution by ID, including the full workflow definition that was used.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Response 200 OK

Returns the full Execution object with an additional definition field containing the workflow nodes and connections as they were at execution time.

{
  "id": "exec_xyz789",
  "workflowId": "wf_abc123",
  "status": "completed",
  "startedAt": "2025-02-01T14:22:00Z",
  "endedAt": "2025-02-01T14:25:30Z",
  "durationMs": 210000,
  "trigger": {
    "type": "manual",
    "data": {}
  },
  "triggerType": "manual",
  "userId": "user_456",
  "organizationId": "org_xyz",
  "config": {},
  "error": null,
  "progress": 100,
  "definition": {
    "nodes": [],
    "connections": []
  },
  "createdAt": "2025-02-01T14:22:00Z",
  "updatedAt": "2025-02-01T14:25:30Z"
}

---

POST /api/v1/executions/:id/stop

Stop a running execution. All in-progress nodes will be terminated.

Scope: workflows:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Response 200 OK

{
  "message": "Execution stop requested",
  "executionId": "exec_xyz789",
  "status": "stopped"
}

Error 409 Conflict

Returned if the execution is not currently running.

{
  "error": "Conflict",
  "message": "Execution is not running",
  "statusCode": 409
}

---

POST /api/v1/executions/:id/resume

Resume a paused or stopped execution.

Scope: workflows:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Request Body

{
  "triggerData": {
    "key": "value"
  }
}

Field	Type	Required	Description
triggerData	object	No	Additional data to pass when resuming

Response 200 OK

{
  "message": "Execution resumed",
  "executionId": "exec_xyz789",
  "status": "running"
}

---

POST /api/v1/executions/:id/input

Submit external input to an execution that is currently in waiting status (e.g. responding to a human-input, feedback, or checkpoint request).

Scope: workflows:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Request Body

Field	Type	Required	Description
request_id	string	Yes	The pending input request ID to respond to (from pending-inputs)
data	any	Yes	Input payload — shape matches the node's expected schema
respondent	string	No	Name of the respondent (defaults to API username or "api")

{
  "request_id": "req_abc123",
  "data": {
    "approved": true,
    "notes": "Looks good"
  },
  "respondent": "jane.doe"
}

Response 200 OK

{
  "success": true,
  "executionId": "exec_xyz789",
  "requestId": "req_abc123"
}

Errors

Status	Code	Description
400	validation-error	Missing request_id or data field
404	not-found	Execution not found
403	forbidden	Caller cannot access this execution's workflow
409	invalid-state	Execution is not in waiting status
502	s3-write-failed	Failed to persist input payload to S3

---

GET /api/v1/executions/:id/pending-inputs

List pending input, feedback, or checkpoint requests for a workflow execution. Walks the parent workflow's state array and returns entries scoped to this execution whose value.status === "pending".

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Response 200 OK

{
  "executionId": "exec_xyz789",
  "workflowId": "wf_abc123",
  "executionStatus": "waiting",
  "pendingInputs": [
    {
      "key": "input_requests/req_abc123",
      "type": "input",
      "requestId": "req_abc123",
      "prompt": "Approve this deployment?",
      "schema": {
        "type": "object",
        "properties": { "approved": { "type": "boolean" } }
      },
      "nodeId": "node_3",
      "createdAt": "2025-02-01T14:24:00Z"
    }
  ]
}

The type field is derived from the state-key prefix: input_requests/ → input, feedback_requests/ → feedback, checkpoints/ → checkpoint, otherwise other.

---

GET /api/v1/executions/:id/spans

List execution spans. Each span represents the execution of a single node within the workflow.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Query Parameters

Parameter	Type	Required	Description
node_id	string	No	Filter spans by node ID

Response 200 OK

[
  {
    "id": "span_001",
    "executionId": "exec_xyz789",
    "nodeId": "node_1",
    "nodeLabel": "Extract Orders",
    "nodeType": "mysql-source",
    "status": "completed",
    "startedAt": "2025-02-01T14:22:01Z",
    "endedAt": "2025-02-01T14:22:45Z",
    "durationMs": 44000,
    "inputData": {},
    "outputData": {
      "rowCount": 1500
    },
    "error": null
  },
  {
    "id": "span_002",
    "executionId": "exec_xyz789",
    "nodeId": "node_2",
    "nodeLabel": "Transform Data",
    "nodeType": "code",
    "status": "completed",
    "startedAt": "2025-02-01T14:22:46Z",
    "endedAt": "2025-02-01T14:24:00Z",
    "durationMs": 74000,
    "inputData": {},
    "outputData": {
      "rowCount": 1450
    },
    "error": null
  }
]

---

GET /api/v1/executions/:id/logs

Get execution logs. Logs are produced by individual nodes during execution and include informational messages, warnings, and errors.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Query Parameters

Parameter	Type	Required	Description
level	string	No	Filter by log level: debug, info, warn, error
limit	integer	No	Number of log entries to return (default: 100, max: 1000)

Response 200 OK

[
  {
    "id": "log_001",
    "executionId": "exec_xyz789",
    "level": "info",
    "message": "Starting MySQL extraction from orders table",
    "nodeId": "node_1",
    "createdAt": "2025-02-01T14:22:01Z"
  },
  {
    "id": "log_002",
    "executionId": "exec_xyz789",
    "level": "info",
    "message": "Successfully extracted 1500 rows from orders table",
    "nodeId": "node_1",
    "createdAt": "2025-02-01T14:22:45Z"
  },
  {
    "id": "log_003",
    "executionId": "exec_xyz789",
    "level": "warn",
    "message": "50 rows skipped due to null primary key",
    "nodeId": "node_2",
    "createdAt": "2025-02-01T14:23:10Z"
  }
]

---

GET /api/v1/executions/:id/progress

Get real-time progress of an execution, including node-level completion counts.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Execution ID

Response 200 OK

{
  "executionId": "exec_xyz789",
  "status": "running",
  "progress": 66,
  "totalNodes": 6,
  "completedNodes": 4,
  "failedNodes": 0,
  "runningNodes": 1,
  "startedAt": "2025-02-01T14:22:00Z",
  "endedAt": null,
  "durationMs": 180000
}