Retrieve a specific flow execution
Retrieve detailed information for a specific flow execution.
Fetch a single flow execution by its unique identifier. Returns execution metadata including status, input data, timestamps, and optionally the sequential run number within its flow.
Context: - Retrieves single execution regardless of status (except deleted) - Soft-deleted executions return 404 Not Found - Includes full input data as provided at creation - Run number calculated on-demand if requested - Useful for monitoring execution progress
Run Number Calculation: - When include_run_number=true, calculates sequential position - Based on creation timestamp among all executions for this flow - Includes deleted executions (may have gaps in visible numbers) - Performance: Adds ~10-20ms per request - Useful for displaying "Run #42" in UI
Use Cases: - Check status of long-running execution - Retrieve input data for debugging - Display execution details in UI - Audit execution history with run numbers - Poll for execution completion
Performance Notes: - Without run_number: ~10ms average response time - With run_number: ~25ms average response time - Highly cacheable (status changes infrequently)
Related Endpoints: - GET /flow-executions - List all executions for a flow - POST /flow-executions/{id}/execute - Re-execute this execution - GET /task-executions?flow_execution_id={id} - Get task details - DELETE /flow-executions/{id} - Delete this execution
Header Parameters
Query Parameters
Calculate and include sequential run number. Adds ~10-20ms overhead. Recommended for UI display only.
Path Parameters
UUID of the flow execution to retrieve. Must exist and not be soft-deleted.
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
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.