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"
}

---

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
}