Skip to main content
GET
Get specific flow version

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_id
string<uuid>
required
version
integer
required

Query Parameters

include_ordered_task_names
boolean
default:false

Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.

include_validation_errors
boolean
default:false

Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.

include_dynamic_data
boolean
default:false

Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.

include_output_schemas
boolean
default:false

Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections.

include_input_schema
boolean
default:false

Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building.

include_default_reference_modes
boolean
default:false

Include each task's default reference modes (single/collection) as the task-level 'default_reference_modes' property. Lets the UI show the resolved default instead of an ambiguous 'Default' option. Cheap to compute.

Response

Flow version successfully retrieved

Response model for a flow object.

Represents a complete flow definition with metadata, execution statistics, and optional computed fields. Use query parameters to include additional fields that require extra processing.

Expansion Parameters

Control which computed fields are included using these query parameters:

  • include_ordered_task_names: Adds task_names field with topological sort
  • include_validation_errors: Adds validation_errors field if flow is invalid
  • include_dynamic_data: Enriches each task in definition with runtime config options
  • include_output_schemas: Enriches each task in definition with JSON schema

Performance Considerations

Each expansion parameter adds processing overhead. Only request fields you need:

  • Base response: ~50-100ms
  • + include_ordered_task_names: +50ms for 20+ tasks
  • + include_dynamic_data: +100-500ms (calls external APIs)
  • + include_output_schemas: +10-50ms
  • + include_validation_errors: No overhead (always validated)
created_at
string<date-time>
required
definition
Definition · object
required

Complete flow definition in DSL format. May be enriched with additional fields when using expansion parameters (include_dynamic_data, include_output_schemas). Enriched fields are added to each task within definition.tasks[].

display_name
string
required

Human-readable flow name

id
string<uuid>
required
is_latest
boolean
required

Whether this is the latest version of the flow

modified_by
string
required
organization_id
string<uuid>
required

Organization that owns this flow

revision
string
required
read-only

Opaque token for the stored state of this flow version: <version>:<hash of the stored definition>. It changes on every definition write, including saves that keep the version (task moves, retitles). Send it back as expected_revision on PUT /definition, PUT /task or POST /versions/{version}/restore to save only if nobody changed the flow since you read it; a stale value returns 409 revision_conflict. Never stored; not affected by expansion parameters.

status
string
required

Flow lifecycle status. Values: 'draft' (editable), 'published' (ready for production use)

updated_at
string<date-time>
required
version
integer
required

Flow version number. Increments on each update.

Required range: x >= 1
awaiting_hitl_executions_count
integer | null

Number of queued, running or awaiting-input runs that hold a Human In The Loop task (either HITL task type) that is still pending or in progress. Runs paused for other input, such as webhook data, are not counted. Populated by the flows list; null when the caller's role cannot read review tasks.

awaiting_input_executions_count
integer | null

Number of awaiting-input runs without an open Human In The Loop task, such as runs waiting on webhook data. Populated by the flows list; null when the caller's role cannot read review tasks.

deleted
boolean
default:false
description
string | null

Detailed flow description

error_executions_count
integer | null

Number of runs that failed, were cancelled or are being cancelled, or that have a failed task (such a run still ends completed unless the flow fails executions on task errors). Populated by the flows list when include_error_executions_count=true or sorting by it.

flow_executions_count
integer
default:0

Total number of times this flow has been executed across all versions

is_hidden
boolean
default:false

Whether an organization admin hid this flow from the Hub. Populated by the flows list.

last_execution_activity_at
string<date-time> | null

When any non-deleted run of this flow was last created or updated — the flow's last processing activity. Null when the flow has never run. Populated by the flows list.

latest_version_executions_count
integer | null

Number of executions on the most recent flow version that has any runs — the dataset calibration samples. Only included when include_latest_version_executions_count=true.

settings
FlowSettings · object | null

Flow-level configuration settings

tags
string[]
task_names
string[] | null

Topologically sorted list of task names in execution order. Only included when include_ordered_task_names=true. Useful for visualizing task dependencies and execution flow.

validation_errors
ErrorDetails · object[] | null

DSL validation errors if the flow definition is malformed. Only included when include_validation_errors=true. Empty list indicates a valid flow. Each error contains location and message details.