Skip to main content
GET
Retrieve a specific flow execution

Authorizations

Authorization
string
header
required

JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN

Example:

Path Parameters

flow_execution_id
string<uuid>
required

UUID of the flow execution to retrieve. Must exist and not be soft-deleted.

Query Parameters

include_credits
boolean
default:false

Include total credits consumed by this execution in the response. When false (default), total_credits is null and the usage table is not queried. Adds a usage-table lookup when enabled.

Response

Flow execution successfully retrieved

Response model for flow execution operations.

Represents a single flow execution instance with its current state and metadata. Flow executions are runtime instances of flow definitions that process input data through a series of tasks defined in the flow's workflow.

created_at
string<date-time>
required
flow_id
string<uuid>
required

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

Example:

"550e8400-e29b-41d4-a716-446655440000"

flow_version
integer
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.

Required range: x >= 1
Example:

3

id
string<uuid>
required
input
Input · object
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.

Example:
modified_by
string
required
organization_id
string<uuid>
required

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

Example:

"660e8400-e29b-41d4-a716-446655440001"

status
enum<string>
required

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.

Available options:
queued,
running,
completed,
failed,
deleted,
stale,
edited,
awaiting_input,
cancel_requested,
cancelled,
pending_payment
Example:

"running"

updated_at
string<date-time>
required
idempotency_key
string | null

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.

Example:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

pricing_config_id
string<uuid> | null

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
AwaitingInputStatusData · object

status_data of a flow execution whose status is awaiting_input.

Example:
total_credits
integer | null

Total credits consumed by this flow execution across all tasks. None when no usage records exist yet.

Example:

42

triggered_task_executor_name
string | null

Executor name of the trigger that fired this execution (e.g., 'receive_file'). Set for multi-input flows; None for single-input-task flows.