List flow executions with filtering and pagination

curl --request GET \
  --url https://flows.super.ai/api/flow-executions \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://flows.super.ai/api/flow-executions"

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/flow-executions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://flows.super.ai/api/flow-executions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/flow-executions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/flow-executions")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/flow-executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "created_at": "2023-11-07T05:31:56Z",
    "flow_id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_version": 3,
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "input": {
      "file_key": "documents/abc123.pdf",
      "metadata": {
        "priority": "high"
      }
    },
    "modified_by": "<string>",
    "organization_id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "running",
    "updated_at": "2023-11-07T05:31:56Z",
    "run_number": 42
  }
]

flow-executions

List flow executions with filtering and pagination

List flow executions with filtering, sorting, and pagination.

Retrieve a paginated list of flow executions for a specific flow with support for filtering by status, tags, and date ranges. Results can be sorted by creation or update time and include optional run number calculation.

Context:

Returns executions for a single flow (specified by flow_id)
Excludes soft-deleted executions from results
Supports multiple filtering dimensions for flexible queries
Pagination uses offset-based approach (page/page_size)
Run numbers calculated on-demand (performance impact)

Filtering Logic:

Status filter: Returns executions containing tasks with ANY of specified statuses
Tag filter: Returns executions containing tasks with ANY of specified tags
Multiple filters combined with AND logic
Empty filters return all executions

Pagination:

Offset-based: page=1, page_size=10 returns first 10 results
Default: page=1, page_size=10
Maximum page_size: 1000 results
Maximum page: 10,000 (to prevent excessive database load)
Use start_from_execution_id for cursor-like pagination

Run Numbers:

include_run_number=true: Calculates sequential number (1, 2, 3…)
Based on creation time for the flow
Includes deleted executions in count (may have gaps)
Performance impact: Additional database query per execution
Recommended: Use only when displaying in UI

Sorting:

sort_field: ‘created_at’ (when execution was created) or ‘updated_at’ (when execution was last modified)
sort_direction: ‘asc’ (oldest first) or ‘desc’ (newest first)
Default: sort by created_at desc (most recently created first)

Performance Considerations:

Without run_number: ~50ms for 100 results
With run_number: ~200ms for 100 results (N+1 query issue)
Consider caching for frequently accessed pages
Large page_size values increase response time linearly

Use Cases:

Display execution history in UI dashboard
Monitor recent execution failures (filter by status=‘failed’)
Find executions by business context (filter by tags)
Export execution audit trail
Identify oldest pending executions (sort by created_at asc)

Example Queries:

Recent failures: ?flow_id=xxx&status=failed&sort_field=created_at&sort_direction=desc&page_size=20
Tagged executions: ?flow_id=xxx&tags=priority:high&tags=customer:acme
Paginated view: ?flow_id=xxx&page=2&page_size=50
With run numbers: ?flow_id=xxx&include_run_number=true

Related Endpoints:

GET /flow-executions/ - Get single execution details
POST /flow-executions - Create new execution
GET /flows/ - Get flow definition details

GET

api

flow-executions

List flow executions with filtering and pagination

curl --request GET \
  --url https://flows.super.ai/api/flow-executions \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://flows.super.ai/api/flow-executions"

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/flow-executions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://flows.super.ai/api/flow-executions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/flow-executions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/flow-executions")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/flow-executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "created_at": "2023-11-07T05:31:56Z",
    "flow_id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_version": 3,
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "input": {
      "file_key": "documents/abc123.pdf",
      "metadata": {
        "priority": "high"
      }
    },
    "modified_by": "<string>",
    "organization_id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "running",
    "updated_at": "2023-11-07T05:31:56Z",
    "run_number": 42
  }
]

Authorizations

X-API-Key

string

header

required

API key authentication. Include your API key in the X-API-Key header as: X-API-Key YOUR_API_KEY

Example:

X-API-Key: saf_1234567890

Authorization

string

header

required

JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Query Parameters

flow_id

string<uuid>

required

UUID of the flow to list executions for. Required parameter.

sort_field

string | null

Field to sort results by. Valid values: 'created_at', 'updated_at'. Defaults to 'created_at' for most recently modified first.

Pattern: ^(created_at|updated_at)$

sort_direction

string | null

Sort order direction. Valid values: 'asc' (ascending), 'desc' (descending). Defaults to 'desc' for newest first.

Pattern: ^(asc|desc)$

status

string[] | null

Filter by execution status. Can specify multiple values. Valid values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'stale'. Returns executions containing tasks with ANY of the specified statuses. Example: ?status=failed&status=running

Response

List of flow executions successfully retrieved

created_at

string<date-time>

required

flow_id

string<uuid>

required

UUID of the flow definition being executed. References the parent flow that defines the workflow structure.

Example:

"550e8400-e29b-41d4-a716-446655440000"

flow_version

integer

required

Version number of the flow definition used for this execution. Execution continues on the same version even if flow is updated. Ensures consistency throughout execution lifecycle.

Required range: x >= 1

Example:

3

string<uuid>

required

input

Input · object

required

Input data provided when execution was created. Schema is defined by the flow definition. Commonly includes: file_key, document_url, or custom parameters. Structure varies by flow type.

Example:

{
  "file_key": "documents/abc123.pdf",
  "metadata": { "priority": "high" }
}

modified_by

string

required

organization_id

string<uuid>

required

UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.

Example:

"660e8400-e29b-41d4-a716-446655440001"

status

string

required

Current execution status. Possible values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'deleted', 'stale'. Status transitions: queued → running → in_progress → completed/failed. Use 'completed' to indicate success, 'failed' for errors.

Example:

"running"

updated_at

string<date-time>

required

run_number

integer | null

Sequential run number for this execution within its flow. Starts at 1 for the first execution and increments by creation time. Includes deleted executions in count, so visible numbers may have gaps. Only populated when include_run_number=true query parameter is set. Null when not requested to avoid performance overhead.

Required range: x >= 1

Example:

42

Resolve storage URI to download URL Create and start a flow execution