List all ActionFlows runs across your flows via the REST API, with optional filtering and pagination. Includes request parameters and response schema.

List Runs

Retrieve all runs across all your flows with optional filtering and pagination.

Endpoint

GET /api/runs

Try it

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

get/api/runs

List runs

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

API key

page[size]

page[after]

page[before]

filter[status]

filter[tag]

filter[createdAt][from]

filter[createdAt][to]

filter[createdAt][period]

filter[isTest]

filter[taskIdentifier]

filter[version]

X-Locale

curl -X GET 'https://api.actionflows.ai/api/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.

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[taskIdentifier]`	string	No	Filter by task identifier. Comma-separated values
`filter[version]`	string	No	Filter by version. Comma-separated values
`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",
        "version": "1.0.0",
        "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

401 Unauthorized

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

429 Too Many Requests

{
  "error": "Too many requests"
}

Example Requests

Get All Runs

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

Get Runs with Filters

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

JavaScript

// Get all runs
const response = await fetch('https://api.actionflows.ai/api/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 with pagination
  const params = new URLSearchParams({
    'filter[status]': 'COMPLETED',
    'filter[isTest]': 'false',
    'page[size]': '20',
  });
  
  const filteredResponse = await fetch(
    `https://api.actionflows.ai/api/runs?${params}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
    }
  );
  
  const filteredData = await filteredResponse.json();
  
  // Paginate to next page
  if (filteredData.data.pagination.next) {
    const nextParams = new URLSearchParams({
      'page[after]': filteredData.data.pagination.next,
      'page[size]': '20',
    });
    
    const nextResponse = await fetch(
      `https://api.actionflows.ai/api/runs?${nextParams}`,
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
        },
      }
    );
  }
}

Python

import requests

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

# Get all runs
response = requests.get('https://api.actionflows.ai/api/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',
        'filter[isTest]': 'false',
        'page[size]': '20',
    }
    
    filtered_response = requests.get(
        'https://api.actionflows.ai/api/runs',
        headers=headers,
        params=params
    )
    
    filtered_data = filtered_response.json()
    
    # Paginate to next page
    if filtered_data['data']['pagination']['next']:
        next_params = {
            'page[after]': filtered_data['data']['pagination']['next'],
            'page[size]': '20',
        }
        
        next_response = requests.get(
            'https://api.actionflows.ai/api/runs',
            headers=headers,
            params=next_params
        )

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[].version`	string	Run version
`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

Returns runs from all flows you have access to
Use pagination for large result sets
Multiple filter values can be specified by comma-separating them
This endpoint is rate-limited per user

List Runs

Try it

On this page