curl --request GET \
--url https://flows.super.ai/api/flow-executions \
--header 'Authorization: Bearer <token>'import requests
url = "https://flows.super.ai/api/flow-executions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {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>"
],
]);
$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("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("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["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",
"idempotency_key": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"pricing_config_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status_data": {
"task_name": "review_invoice"
},
"total_credits": 42,
"triggered_task_executor_name": "<string>"
}
]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.
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)
Filtering Logic:
- Status filter: Returns executions containing tasks with ANY of specified statuses
- Tag filter: Returns executions containing tasks with ANY of the specified tags, or with ALL of them (anywhere in the run) when tags_mode=all
- Date range: created_after/created_before bound created_at; updated_after/updated_before bound updated_at (all inclusive, ISO 8601)
- 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
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:
- ~50ms for 100 results
- 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
- Completed in window: ?flow_id=xxx&status=completed&created_after=2026-06-18T08:00:00Z&created_before=2026-06-18T10:00:00Z
Related Endpoints:
- GET /flow-executions/ - Get single execution details
- POST /flow-executions - Create new execution
- GET /flows/ - Get flow definition details
curl --request GET \
--url https://flows.super.ai/api/flow-executions \
--header 'Authorization: Bearer <token>'import requests
url = "https://flows.super.ai/api/flow-executions"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {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>"
],
]);
$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("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("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["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",
"idempotency_key": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"pricing_config_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status_data": {
"task_name": "review_invoice"
},
"total_credits": 42,
"triggered_task_executor_name": "<string>"
}
]Authorizations
JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN
Example:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Query Parameters
UUID of the flow to list executions for. Required parameter.
Field to sort results by. Valid values: 'created_at', 'updated_at'. Defaults to 'created_at' for most recently modified first.
^(created_at|updated_at)$Sort order direction. Valid values: 'asc' (ascending), 'desc' (descending). Defaults to 'desc' for newest first.
^(asc|desc)$Filter by flow execution status. Can specify multiple values. Valid values: 'queued', 'running', 'completed', 'failed', 'stale', 'awaiting_input', 'cancel_requested', 'cancelled', 'edited', 'pending_payment'. Returns executions whose overall status matches ANY of the specified values. Example: ?status=failed&status=running
Exclude flow executions whose status matches any of these values. Mirrors tags/tags_exclude. Combines with status using AND. Example: ?status_exclude=queued hides queued runs from the result and total count.
Filter by task tags. Can specify multiple values, connected by tags_mode. Tags use key:value format. Example: ?tags=priority:high&tags=env:prod
50Connector between the tags values. 'any' (default) returns executions carrying at least one of them; 'all' returns executions carrying every tag, matched at run level so the tags may sit on different tasks. Example: ?tags=doc:invoice&tags=error:amount&tags_mode=all
any, all Page number for pagination (1-indexed). Minimum: 1, Maximum: 10,000. Works with page_size to implement offset-based pagination.
1 <= x <= 10000Number of results to return per page. Minimum: 1, Maximum: 1000. Larger values increase response time. Recommended: 10-100.
1 <= x <= 1000Start listing after this execution ID. Provides cursor-like pagination. When combined with sort parameters, returns results after the specified execution. Useful for infinite scroll or keyset pagination patterns.
Return executions created at or after this timestamp (inclusive). Accepts ISO 8601 (e.g. '2026-06-18T08:00:00Z'). Combined with other filters using AND.
Return executions created at or before this timestamp (inclusive). Accepts ISO 8601 (e.g. '2026-06-18T10:00:00Z'). Combined with other filters using AND.
Return executions last updated at or after this timestamp (inclusive). Accepts ISO 8601. Combined with other filters using AND.
Return executions last updated at or before this timestamp (inclusive). Accepts ISO 8601. Combined with other filters using AND.
Include total credits consumed by each execution in the response. When false (default), total_credits is null and the usage table is not queried. Adds a single bulk usage-table lookup for the page when enabled.
Response
List of flow executions successfully retrieved
UUID of the flow definition being executed. References the parent flow that defines the workflow structure.
"550e8400-e29b-41d4-a716-446655440000"
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.
x >= 13
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.
{
"file_key": "documents/abc123.pdf",
"metadata": { "priority": "high" }
}
UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.
"660e8400-e29b-41d4-a716-446655440001"
Current execution status. Possible values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale', 'edited', 'awaiting_input', 'cancel_requested', 'cancelled', 'pending_payment'. Status transitions: queued → running → completed/failed. 'pending_payment' means the execution is held until the organization's credits are restored, then released back to 'queued' automatically.
queued, running, completed, failed, deleted, stale, edited, awaiting_input, cancel_requested, cancelled, pending_payment "running"
Idempotency key this execution was created with: the Idempotency-Key request header when the caller sent one, otherwise a ULID generated by super.AI. Sending a create request for the same flow with this key again returns this execution with 201, in its current state, instead of creating or starting a new one. Null only for executions created before idempotency keys existed.
"01ARZ3NDEKTSV4RRFFQ69G5FAV"
UUID of the pricing config active when this execution was created or re-executed. References the default config if no org-specific config existed at that time. None for executions created before pricing config tracking was introduced.
status_data of a flow execution whose status is awaiting_input.
- AwaitingInputStatusData
- FailedStatusData
Show child attributes
Show child attributes
{ "task_name": "review_invoice" }
Total credits consumed by this flow execution across all tasks. None when no usage records exist yet.
42
Executor name of the trigger that fired this execution (e.g., 'receive_file'). Set for multi-input flows; None for single-input-task flows.