Runs API
Trigger and monitor integration run executions
Runs API
Endpoints
POST /api/integrations/:name/runs
Trigger a manual run for an integration.
Auth: API Key | Min Role: DEVELOPER | MCP: runs:write
Body: { "payload": { "key": "value" } } (optional)
Response: 202 { "runId": "run_abc123" }
GET /api/runs
List runs for the workspace with pagination.
Auth: API Key | Min Role: VIEWER | MCP: runs:read
Query parameters:
| Parameter | Description |
|---|---|
status | PENDING | RUNNING | SUCCEEDED | FAILED | CANCELLED |
integrationId | Filter by integration ID |
search | Full-text search on integration name, error message, trigger type |
dateFrom | ISO date string — filter runs started on or after this date |
dateTo | ISO date string — filter runs started on or before this date |
page | Page number (default: 1) |
limit | Items per page, max 100 (default: 20) |
Response: { "runs": [...], "total": 42, "page": 1, "limit": 20 }
GET /api/runs/:runId
Get run detail including step logs.
Auth: API Key | Min Role: VIEWER | MCP: runs:read
Response: Run object with stepLogs array.
GET /api/runs/:runId/steps
Get step events for a run.
Auth: API Key | Min Role: VIEWER | MCP: runs:read
Query: outputPath (optional) — absolute server path to write the response if >40KB.
Response: { "steps": [...] }
GET /api/runs/:runId/stream
Server-sent events (SSE) stream for real-time run progress.
Auth: API Key | Min Role: VIEWER
Response: text/event-stream
Run Status Values
| Status | Description |
|---|---|
PENDING | Run is queued but not yet started |
RUNNING | Run is currently executing |
SUCCEEDED | All steps completed successfully |
FAILED | One or more steps failed without an error handler |
CANCELLED | Run was manually cancelled |