List all runs for a specific ActionFlow via the REST API, with optional filtering and pagination. Includes parameters and response schema.

List Flow Runs

Retrieve run history for a specific ActionFlow from Postgres, with optional filtering and cursor pagination.

Endpoint

GET /api/actionflows/{actionFlowId}/runs

Try it

Live requests run from your browser. Open the API Explorer to try every operation from one screen.

get/api/actionflows/{actionFlowId}/runs

List runs for a flow

Requests go to the live API from your browser. The docs server never sees this key.

API key

actionFlowId *

page[size]

page[after]

page[before]

filter[status]

filter[tag]

filter[createdAt][from]

filter[createdAt][to]

filter[createdAt][period]

filter[isTest]

X-Locale

curl -X GET 'https://api.actionflows.ai/api/actionflows/{actionFlowId}/runs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Response

Send a request to see the response.

Authentication

Required. See API Reference for authentication details.

Path Parameters

Parameter	Type	Required	Description
`flowId`	string	Yes	The unique identifier of the flow

Query Parameters

Pagination

Parameter	Type	Required	Description
`page[size]`	number	No	Number of results per page
`page[after]`	string	No	Cursor for pagination (get results after this cursor)
`page[before]`	string	No	Cursor for pagination (get results before this cursor)

Filters

Parameter	Type	Required	Description
`filter[status]`	string	No	Filter by run status. Comma-separated values: `COMPLETED`, `FAILED`, `CANCELED`, `CRASHED`, `TIMED_OUT`, `WAITING`, `EXECUTING`, `PAUSED`
`filter[tag]`	string	No	Filter by tags. Comma-separated values
`filter[createdAt][from]`	string (ISO 8601)	No	Filter runs created after this date
`filter[createdAt][to]`	string (ISO 8601)	No	Filter runs created before this date
`filter[createdAt][period]`	string	No	Filter by time period (for example, `today`, `week`, `month`)
`filter[isTest]`	boolean	No	Filter test runs (`true` or `false`)

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "run_123",
        "status": "COMPLETED",
        "taskIdentifier": "run-flow",
        "payload": {
          "organizationId": "org_123",
          "actionFlowId": "flow_123"
        },
        "tags": ["production"],
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:05:00.000Z",
        "startedAt": "2024-01-01T00:00:01.000Z",
        "completedAt": "2024-01-01T00:05:00.000Z"
      }
    ],
    "pagination": {
      "next": "cursor_123",
      "prev": "cursor_456"
    }
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "Invalid flow ID"
}

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "message": "Authentication required"
}

403 Forbidden

{
  "success": false,
  "error": "Unauthorized",
  "message": "Organization access denied"
}

404 Not Found

{
  "success": false,
  "error": "Flow not found"
}

Example Requests

Get All Runs for a Flow

curl -X GET https://api.actionflows.ai/api/actionflows/flow_123/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get Runs with Filters

curl -X GET "https://api.actionflows.ai/api/actionflows/flow_123/runs?filter[status]=COMPLETED,FAILED&filter[isTest]=false&page[size]=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript

const flowId = 'flow_123';

// Get all runs
const response = await fetch(`https://api.actionflows.ai/api/actionflows/${actionFlowId}/runs`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

if (data.success) {
  const runs = data.data.data;
  console.log(`Found ${runs.length} runs`);
  
  // Get completed runs only
  const params = new URLSearchParams({
    'filter[status]': 'COMPLETED',
    'filter[isTest]': 'false',
    'page[size]': '20',
  });
  
  const filteredResponse = await fetch(
    `https://api.actionflows.ai/api/actionflows/${actionFlowId}/runs?${params}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
    }
  );
  
  const filteredData = await filteredResponse.json();
}

Python

import requests
from urllib.parse import urlencode

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

flow_id = 'flow_123'

# Get all runs
response = requests.get(
    f'https://api.actionflows.ai/api/actionflows/{flow_id}/runs',
    headers=headers
)

data = response.json()

if data['success']:
    runs = data['data']['data']
    print(f"Found {len(runs)} runs")
    
    # Get completed runs with filters
    params = {
        'filter[status]': 'COMPLETED,FAILED',
        'filter[isTest]': 'false',
        'page[size]': '20',
    }
    
    filtered_response = requests.get(
        f'https://api.actionflows.ai/api/actionflows/{flow_id}/runs',
        headers=headers,
        params=params
    )
    
    filtered_data = filtered_response.json()

Response Fields

Field	Type	Description
`data`	array	Array of run objects
`data[].id`	string	Unique run identifier (starts with `run_`)
`data[].status`	string	Run status
`data[].taskIdentifier`	string	Task identifier
`data[].payload`	object	Run payload including `organizationId` and `actionFlowId`
`data[].tags`	array	Run tags
`data[].createdAt`	string (ISO 8601)	Run creation timestamp
`data[].updatedAt`	string (ISO 8601)	Last update timestamp
`data[].startedAt`	string (ISO 8601)	Run start timestamp
`data[].completedAt`	string (ISO 8601)	Run completion timestamp (if completed)
`pagination`	object	Pagination information
`pagination.next`	string	Cursor for next page
`pagination.prev`	string	Cursor for previous page

Run Status Values

COMPLETED - Run finished successfully
FAILED - Run failed with an error
CANCELED - Run was canceled
CRASHED - Run crashed unexpectedly
TIMED_OUT - Run exceeded time limit
WAITING - Run is waiting to start
EXECUTING - Run is currently executing
PAUSED - Run is paused

Notes

Only runs for the specified flow are returned
Runs are filtered by the flow's organizationId and actionFlowId
Use pagination for large result sets
Multiple status values can be specified by comma-separating them
Multiple tags can be specified by comma-separating them

List Flow Runs

Try it

On this page