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
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 'updated_at' for most recently modified first.
Sort order direction. Valid values: 'asc' (ascending), 'desc' (descending). Defaults to 'desc' for newest first.
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
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
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.
Page number for pagination (1-indexed). Minimum: 1, Maximum: 10,000. Works with page_size to implement offset-based pagination.
Number of results to return per page. Minimum: 1, Maximum: 1000. Larger values increase response time. Recommended: 10-100.
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
Response Attributes
UUID of the flow definition being executed. References the parent flow that defines the workflow structure.
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.
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
UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.
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.
Response Attributes
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
Response Attributes
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
Response Attributes
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
Response Attributes
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
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.