Workflow Runs
Documentation for Workflow Runs
Base path: /api/v1/workflow-runs
A workflow run is a single execution instance of a workflow. You can execute workflows, monitor their progress in real time via SSE, and cancel runs.
Note: The list, get, dashboard stats, and cancel endpoints use
privateSvcAuthMiddleware, meaning they accept either a valid JWT (for user-facing calls proxied through the backend) or a private-IP / trusted internal call. Frontend applications should proxy these through their own backend rather than calling them directly with a JWT.
Endpoints Overview
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/v1/workflow-runs/execute | JWT or internal | Execute a workflow (blocking) |
| POST | /api/v1/workflow-runs/execute/stream | JWT or internal | Execute a workflow (SSE stream) |
| POST | /api/v1/workflow-runs/cancel | JWT or internal | Cancel one or more runs |
| GET | /api/v1/workflow-runs | JWT or internal | List workflow runs |
| GET | /api/v1/workflow-runs/dashboard/:workflowId | JWT or internal | Get run counts by status |
| GET | /api/v1/workflow-runs/:runId | JWT or internal | Get a single run with activity runs |
POST /api/v1/workflow-runs/execute
Executes a workflow synchronously (blocking). Waits for the workflow to complete before returning the result.
Warning: This can be long-running. For UI applications, prefer the streaming endpoint instead.
Request Body (multipart/form-data)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workflowId | string (UUID) | Yes | – | ID of the workflow to execute |
inputs | JSON object | No | {} | Input values keyed by input name |
envs | JSON object | No | {} | Environment variable overrides (string-to-string) |
Response 200 OK
POST /api/v1/workflow-runs/execute/stream
Executes a workflow and streams real-time progress updates via SSE.
Request Body (multipart/form-data)
Same fields as the blocking execute endpoint: workflowId, inputs, envs.
Response
Returns an SSE stream (Content-Type: text/event-stream).
SSE Events:
| Event | Data Shape | Description |
|---|---|---|
ping | { "content": "ping" } | Keep-alive, every 9 seconds |
activity-run | { "content": { "workflowRunId": "...", "status": "..." } } | Activity (step) status update |
workflow-run | { "content": { "workflowRunId": "...", "status": "..." } } | Workflow run status update |
thinking | { "content": "<text>", "stepId": "...", "activityRunId": "..." } | AI reasoning trace for a step |
result | { "success": true, "workflowRun": { ... } } | Final result when complete |
error | { "error": "...", "details": "..." } | Execution failure |
Example (JavaScript)
POST /api/v1/workflow-runs/cancel
Cancels one or more workflow runs. You can cancel by specific run IDs or cancel all runs for a workflow.
Request Body (JSON)
Provide either runIds or workflowId (not both).
| Field | Type | Required | Description |
|---|---|---|---|
runIds | string[] | No* | Array of run IDs to cancel |
workflowId | string (UUID) | No* | Cancel all non-terminal runs for this workflow |
reason | string | No | Reason for cancellation (max 500 chars) |
*At least one of runIds or workflowId must be provided.
Response 200 OK
Outcome status values:
| Status | Description |
|---|---|
cancelled | Successfully cancelled |
already_completed | Run was already in a terminal state (completed/failed) |
not_eligible | Run was already cancelled or has no Temporal workflow |
not_found | Run ID not found |
error | Cancellation failed (Temporal error) |
GET /api/v1/workflow-runs
Lists workflow runs with optional filtering.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
workflowId | string (UUID) | – | Filter by workflow ID |
status | string | – | Filter by status: scheduled, running, completed, failed, cancelled, waiting |
page | number | 1 | Page number |
limit | number | 10 | Items per page (min: 1, max: 100) |
search | string | – | Search by workflow name |
Response 200 OK
Workflow run fields:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Run ID |
workflowId | string (UUID) | Parent workflow ID |
workflowName | string | null | Workflow name at time of run |
status | string | Run status |
inputs | array | Input values used for this run |
createdAt | string (ISO 8601) | When the run was created |
updatedAt | string (ISO 8601) | Last status update time |
Run status values: scheduled, running, completed, failed, cancelled, waiting
GET /api/v1/workflow-runs/dashboard/:workflowId
Returns a count breakdown of runs by status for a specific workflow. Useful for dashboard widgets.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
workflowId | string (UUID) | Workflow ID |
Response 200 OK
GET /api/v1/workflow-runs/:runId
Returns a single workflow run including all its activity (step) runs.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
runId | string (UUID) | Workflow run ID |
Response 200 OK
Activity run fields:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Activity run ID |
stepId | string | Workflow step ID |
stepName | string | null | Step name |
status | string | Step status |
outputs | object | null | Step output data |
attempt | number | Retry attempt number (1-indexed) |
createdAt | string (ISO 8601) | Start time |
updatedAt | string (ISO 8601) | Last update time |