Flow Runs API

Retrieve execution history and trigger manual runs programmatically.

List Runs

Get execution history for a specific flow.

GET /api/v1/flows/{flowId}/runs

Query Parameters:

Parameter	Type	Description
limit	integer	Max results per page (default: 10, max: 100)
cursor	string	Pagination cursor
status	string	Filter: SUCCEEDED, FAILED, RUNNING

Example:

curl -X GET "https://app.onflowstack.com/api/v1/flows/flow_abc123/runs?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "run_xyz789",
      "flowId": "flow_abc123",
      "status": "SUCCEEDED",
      "duration": 2340,
      "triggerType": "SCHEDULE",
      "startTime": "2026-04-21T09:00:00Z",
      "finishTime": "2026-04-21T09:00:02.340Z",
      "stepsCount": 5,
      "stepsSucceeded": 5
    },
    {
      "id": "run_uvw456",
      "flowId": "flow_abc123",
      "status": "FAILED",
      "duration": 1200,
      "triggerType": "SCHEDULE",
      "startTime": "2026-04-20T09:00:00Z",
      "finishTime": "2026-04-20T09:00:01.200Z",
      "stepsCount": 5,
      "stepsSucceeded": 3,
      "error": {
        "step": "Send Slack Message",
        "message": "channel_not_found: The specified channel does not exist"
      }
    }
  ],
  "cursor": "eyJpZCI6InJ1bl91dncyMzQifQ==",
  "hasMore": true
}

Get Run Details

Retrieve detailed execution data for a specific run, including step-by-step input/output.

GET /api/v1/flows/{flowId}/runs/{runId}

Response:

{
  "id": "run_xyz789",
  "flowId": "flow_abc123",
  "status": "SUCCEEDED",
  "duration": 2340,
  "startTime": "2026-04-21T09:00:00Z",
  "finishTime": "2026-04-21T09:00:02.340Z",
  "steps": [
    {
      "name": "Schedule Trigger",
      "status": "SUCCEEDED",
      "duration": 5,
      "output": { "scheduledTime": "2026-04-21T09:00:00Z" }
    },
    {
      "name": "Query Database",
      "status": "SUCCEEDED",
      "duration": 450,
      "output": { "rowCount": 24, "totalRevenue": 12500.00 }
    },
    {
      "name": "Format Report",
      "status": "SUCCEEDED",
      "duration": 15,
      "output": { "reportText": "Daily Sales Report: 24 orders, $12,500 revenue" }
    },
    {
      "name": "Send Slack Message",
      "status": "SUCCEEDED",
      "duration": 870,
      "output": { "messageId": "1234567890.123456", "channel": "#sales" }
    }
  ]
}

Trigger Manual Run

Start a flow execution programmatically.

POST /api/v1/flows/{flowId}/runs

Request Body (optional):

{
  "data": {
    "customField": "value",
    "userId": "user_123"
  }
}

The data object is passed to the flow as trigger data, accessible in expressions as {{trigger.body}}.

Response: 201 Created

{
  "id": "run_new123",
  "flowId": "flow_abc123",
  "status": "RUNNING",
  "startTime": "2026-04-21T10:45:00Z"
}

Run Statistics

Get aggregated statistics for a flow's runs.

GET /api/v1/flows/{flowId}/runs/stats

Response:

{
  "totalRuns": 145,
  "succeeded": 143,
  "failed": 2,
  "successRate": 98.6,
  "averageDuration": 2150,
  "lastRun": "2026-04-21T09:00:00Z"
}