Skip to main content
GET
Get Run

Behavior

  • Poll this endpoint with the id returned by Run until status reaches a terminal value (COMPLETED, FAILED, CANCELLED, or SKIPPED), or register a webhook for flow_run_completed and flow_run_failed. The webhook includes the terminal run object; structured output is read separately with Get Run Output.
  • report is the full analyst-facing result as Markdown text when the Flow produces one. A completed structured-only Flow may omit it.
  • output_ref is set once structured output has been captured for the run. Its presence (not its value) is the signal that Get Run Output can be called to read the structured output.
  • error is only set when status is FAILED.
  • degraded is true when one or more tool calls failed even though the Flow finished. failed_sources groups those failures by tool namespace and count.
  • Fields that are not available are omitted rather than returned as null.
  • Returns 404 if runId does not exist, or belongs to a different customer.

Authorizations

X-API-KEY
string
header
required

Path Parameters

runId
string
required

The run's id, returned by POST /flows/{flowId}/runs

Response

OK

id
string<uuid>
required
customer_id
string
required
flow_id
string
required
flow_version_id
string
required
status
enum<string>
required

QUEUED: awaiting worker pickup. RUNNING: executing. COMPLETED/FAILED/CANCELLED/SKIPPED: terminal states.

Available options:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
CANCELLED,
SKIPPED
triggered_at
string<date-time>
required
trigger_type
enum<string>
required
Available options:
manual,
api,
external_event,
schedule,
evaluation
triggered_by
string
required

User email for a manual run; service_account for API and automated runs.

input
object
required

The input the run was triggered with.

created_at
string<date-time>
required
updated_at
string<date-time>
required
started_at
string<date-time>

Set once the run moves from QUEUED to RUNNING.

completed_at
string<date-time>

Set once the run reaches a terminal state.

skip_reason
string

Why the trigger guard skipped the run. Set only when status is SKIPPED.

report
string

The analyst-facing Markdown report when the Flow produces one. A completed structured-only Flow may omit this field.

output_ref
string

Present once structured output has been captured. Its presence means GET /flow-runs/{runId}/output can be called to read it.

log_ref
string

Reference to the run's execution log when one was captured.

error
object

Set only when status is FAILED.

meta
object
records
object[]
run_mode
enum<string>

Present only for rehearsal runs.

Available options:
rehearsal
act_intents
object[]

External actions the rehearsal would have performed.

degraded
boolean

True when one or more tool calls failed, even if the run completed.

failed_sources
object[]

Failed tool calls grouped by namespace.