List task executions with filtering
List task executions with optional filtering by flow execution, task name, or execution index.
Overview Retrieve task executions across all flows in your organization. Results can be filtered by parent flow execution, specific task name, or execution index. Returns task executions with their associated tags for categorization and filtering.
Filtering Logic Multiple filters are combined with AND logic:
- flow_execution_id AND task_name → All executions of a specific task in a flow
- flow_execution_id AND task_execution_idx → All tasks at a specific execution index
- All three filters → Exact task execution lookup (equivalent to GET /{id})
Common Query Patterns
- All tasks in a flow execution: ?flow_execution_id={id}
- Specific task across retries: ?flow_execution_id={id}&task_name=send_email
- First execution of all tasks: ?flow_execution_id={id}&task_execution_idx=0
- All task executions (no filters): Returns all executions in organization
Response Format Returns TaskExecutionWithTagsAPI objects containing:
- Full task execution details (input, output, error, status)
- Associated tags (e.g., reviewed, approved, flagged)
- Metadata (created_at, updated_at, modified_by)
- Organization context for multi-tenant isolation
Performance Considerations
- Queries are scoped to organization_id via RLS policies (automatic filtering)
- Add flow_execution_id filter for better query performance on large datasets
- Unfiltered queries may return large result sets; pagination planned for future
Tags Task tags provide categorization and workflow state:
- Tag types: 'review_status', 'approval', 'quality', 'custom'
- Tags are returned with each task execution for filtering and display
- Soft-deleted tags are excluded from results
Related Endpoints
- GET /task-executions/{id} - Get single task execution by ID
- GET /task-tags - List all tags for a flow execution
- POST /task-executions - Create new task execution
Header Parameters
Query Parameters
Filter task executions by parent flow execution ID. Returns only tasks belonging to the specified flow execution. Combines with other filters using AND logic. Omit to search across all flow executions in your organization.
Filter task executions by exact task name (case-sensitive). Returns all execution attempts of the named task. Useful for tracking retries or finding specific task types. Must match task name exactly as defined in flow definition YAML.
Filter task executions by execution index (zero-based). Returns tasks at a specific execution attempt number. Index 0 = first execution, 1 = first retry, 2 = second retry, etc. Useful for comparing initial vs retry executions or finding specific attempts.
Response
Response Attributes
Array of task execution objects matching the filter criteria. Each object includes full task execution details plus associated tags. Empty array if no executions match filters. Results are ordered by created_at descending (newest first).
Show child attributes
Response Attributes
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.