SuperAI Flow Platform

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 updated_at desc (most recently updated 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/{id} - Get single execution details - POST /flow-executions - Create new execution - GET /flows/{id} - Get flow definition details

Header Parameters

Authorizationstring

Query Parameters

flow_idstring Required

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

sort_fieldstring

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

sort_directionstring

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

statusstring

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

tagsstring

Filter by task tags. Can specify multiple values. Returns executions containing tasks with ANY of the specified tags. Tags use key:value format. Example: ?tags=priority:high&tags=env:prod

include_run_numberboolean

Calculate sequential run number for each execution. Run numbers start at 1 and increment based on creation time. Warning: Adds performance overhead (~150ms per 100 executions). Recommended only for UI display purposes.

Default value

false

pageinteger

Page number for pagination (1-indexed). Minimum: 1, Maximum: 10,000. Works with page_size to implement offset-based pagination.

Minimum

Maximum

10000

Default value

page_sizeinteger

Number of results to return per page. Minimum: 1, Maximum: 1000. Larger values increase response time. Recommended: 10-100.

Minimum

Maximum

1000

Default value

start_from_execution_idstring

Start 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.

Response

200

Object

List of flow executions successfully retrieved

Response Attributes

created_atstring Required

flow_idstring Required

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

flow_versioninteger 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.

Minimum

idstring Required

inputobject 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.

Show child attributes

modified_bystring Required

organization_idstring Required

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

run_numbernull

Minimum

statusstring 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.

updated_atstring Required

400

Object

Bad Request - Invalid query parameters

Response Attributes

errorobject Required

Standard error detail structure.

This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.

Show child attributes

request_idnull

403

Object

Forbidden - User lacks permission to view this flow's executions

Response Attributes

errorobject Required

Standard error detail structure.

This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.

Show child attributes

request_idnull

404

Object

Not Found - The requested resource does not exist

Response Attributes

errorobject Required

Standard error detail structure.

This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.

Show child attributes

request_idnull

422

Object

Unprocessable Entity - Request validation failed

Response Attributes

errorobject Required

Standard error detail structure.

This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.

Show child attributes

request_idnull

500

Object

Internal Server Error - An unexpected error occurred

Response Attributes

errorobject Required

Standard error detail structure.

This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.

Show child attributes

request_idnull

Sections

List flow executions with filtering and pagination

Header Parameters

Query Parameters

Response

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Sections

List flow executions with filtering and pagination

Header Parameters

Query Parameters

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Ask an AI

Code with AI

Response