Skip to main content
POST
Create and start a 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:

Headers

Idempotency-Key
string | null

Optional key that makes this request safe to retry. Must be a ULID: 26 upper-case Crockford base32 characters, e.g. 01ARZ3NDEKTSV4RRFFQ69G5FAV. Keys are scoped to the flow: if an execution of this flow with this key already exists, that execution is returned with 201 in its current state (its status may have changed since it was created, and is deleted if it was deleted) and no new execution is created, started or queued, whatever input the repeat carries. The same key on a different flow creates a separate execution. Keys never expire. If omitted, super.AI generates one. The key in effect is returned as idempotency_key. A malformed key returns 422 and creates nothing.

Required string length: 26
Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example:

"01ARZ3NDEKTSV4RRFFQ69G5FAV"

Body

application/json

Request payload for creating a new flow execution.

This model defines the required data to start a new flow execution. The input schema must match the flow definition's expected input structure.

flow_id
string<uuid>
required

UUID of the flow definition to execute. Must be a valid, active flow accessible to your organization. The flow defines the workflow structure and task sequence.

Example:

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

input
Input · object
required

Input data for the flow execution. Schema is flow-specific. Common patterns: - Document processing: {'file_key': 'path/to/file.pdf'} - Data processing: {'document_url': 'gs://bucket/file.csv'} - Email processing: {'message_id': 'msg_123', 'attachments': []} Refer to flow definition for exact schema requirements.

Example:
input_task_name
string | null

The task name of the input task that is firing this execution. Required when the flow has multiple input trigger tasks — omitting it will result in a validation error. For single-input-task flows this field is optional, but if provided it must exactly match the flow's only input task name; a mismatch returns a 400 error.

Example:

"receive_email"

Response

Flow execution created and started successfully

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.