Skip to main content

Orchestrations

Multi-step pipelines declared as a graph — agents, tools, conditions, humans — versioned, and executed as runs you can poll, resume and cancel.

Overview​

An orchestration is a definition: nodes say what to do (call an agent, call a tool, transform state, ask a person, wait, loop, poll) and edges say what follows what, optionally under a condition. Running one produces an orchestration run, which carries the accumulated state, the artifact each node produced, and its own status. Branch an orchestration builds a condition node and the conditional edges it chooses between.

Where a workflow models one item of work moving through states, an orchestration models one pipeline over many steps — and a workflow state can dispatch one, which is how the two compose.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path. It serves two collections — /orchestrations and /orchestration-runs.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Orchestrations.

Data Model​

Orchestration​

FieldTypeDescription
idstringPublic ID (orch_...).
project_idstringPublic ID of the owning project.
namestringHuman-readable name.
descriptionstring, nullableOptional description.
versionintegerIncremented on every write that changes the graph; prior versions are archived. A run pins the version it started on, so these fields are a draft for runs started from now on rather than a live rewrite of the ones already executing.
nodesobject[]
edgesobject[]
state_schemaobject, nullableOptional JSON Schema for state validation.
input_schemaobject, nullableSchema for run inputs (initial state).
output_mappingobject, nullableThe shape of a completed run's output, owned by the orchestration rather than by its terminal node ids. Each key is an output field (a dotted key such as summary.title builds a nested object, and no segment may be __proto__, constructor or prototype); each value is JSON Logic (https://jsonlogic.com) evaluated against { "state": <final run state> }, which includes state.input and state.nodes.<id>. A missing path maps to null; a mapping that throws fails the run. Null (or omitted) keys output by terminal node id. Versioned with the graph; null on update clears it.
created_atstring (date-time)
updated_atstring (date-time)

nodes say what each step does; edges are { from, to, condition? }, plus activation grouping for joins.

OrchestrationNode​

FieldTypeDescription
idstringUnique node identifier within this orchestration.
typestringNode execution type. Known types: agent, tool, transform, knowledge, condition, human, approval, loop, poll, delay, webhook, emit_event, sub_orchestration. Open set — new types may be added in minor releases, and an unrecognized type is accepted at create time (the run fails when the node dispatches), so clients must tolerate unknown values.
agent_idstringFor agent nodes — public ID of the agent to invoke.
tool_idstringFor tool and poll nodes — public ID of the tool to call.
operation_idstringFor tool and poll nodes — specific operation/action on mcp and builtin tools.
expressionanyFor transform/condition nodes — JSON Logic rule (https://jsonlogic.com) evaluated against the run state. A rule may be any JSON value (object, string, number, boolean, array), so no type is constrained.
exit_conditionanyFor poll nodes — JSON Logic stop condition, evaluated each attempt against the run state augmented with response (the latest tool result) and attempt (1-based count); a truthy result stops polling.
promptstringFor human nodes — prompt shown to the human reviewer.
optionsstring[]For human nodes — constrained choices.
argumentsobjectFor approval nodes — input-mapping-style object (JSON Logic values) resolved against run state into the proposed tool call's arguments, frozen onto the created approval item.
expires_inintegerFor approval nodes — seconds until the created approval item expires. Defaults to 86400 (24h) when omitted. An expired item can never execute; the run routes down its on_expired edge.
instructionsstringFor approval nodes — optional guidance shown to the approver.
reasoninganyFor approval nodes — JSON Logic (any JSON value) resolved into the item's reasoning.
evidenceanyFor approval nodes — JSON Logic (any JSON value) resolved into the item's evidence.
predicted_impactanyFor approval nodes — JSON Logic (any JSON value) resolved into the item's predicted impact.
input_mappingobjectMaps node input keys to values. Each value is JSON Logic (https://jsonlogic.com), the same evaluator used by transform and condition nodes. A single-key object is evaluated against the run state — {"var": "key"} reads state.key, {"cat": [...]} and {">": [...]} compute derived values. Any other value (string, number, boolean, array, multi-key object) is passed through as a literal.
state_mappingobjectMaps state write paths to values. Each key is a state.<path> destination (the state. prefix is optional); each value is JSON Logic (https://jsonlogic.com) evaluated against { "output": <node artifact>, "state": <run state> } — e.g. { "summary": {"var": "output.content"} } writes the artifact's content field to state.summary. The same evaluator as input_mapping/transform/condition; only the context differs. No key segment may be __proto__, constructor or prototype. An agent node's artifact always carries both content (the text response) and object (the parsed value when a schema applied, null otherwise), so output.content reads the same whether or not the node declares an output_schema.
output_schemaobjectFor agent nodes — JSON Schema the model's answer is parsed into, reaching the artifact as object. Declaring it here is only needed for an agent that carries no output_schema of its own: the agent's schema already produces the artifact's object wherever that agent generates.
collectionstringFor loop nodes — state path to the collection to iterate over.
item_variablestringFor loop nodes — variable name injected into state for each item.
parallelismintegerFor loop nodes — number of items to process in parallel.
on_item_errorfail | collectFor loop nodes — what a failed item does. fail (the default) fails the node on the first item whose child run settles failed, cancelled or expired. collect keeps going: that item's entry in results becomes { "error": { "code", "message" }, "orchestration_run_id" }, in its original position. Either way the artifact carries failed_count. A child run that could not be started (for example past the nesting depth bound) fails the node in both modes.
context_keysstring[], nullableFor loop and sub_orchestration nodes — allowlist of the run's tool_context keys the child run inherits. When null (the default), the child inherits the parent's whole bag. When set, only the listed keys are handed down, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; [] hands down nothing. Matching is case-insensitive, since an entry names a key that becomes an HTTP header name; an entry outside that grammar is rejected at write time with INVALID_TOOL_CONTEXT_KEY. The server-derived identity keys (session_id, actor_id, actor_external_id) are unaffected — they are re-derived per generation in the child regardless of this list. Ignored for other node types.
item_tool_contextobjectFor loop nodes — per-item tool_context keys for each child run. Each key is a tool_context key; each value is JSON Logic evaluated against { <item_variable>: <item>, "state": <run state> }. A child's bag is the inherited one (after context_keys) with these keys laid over it, matched case-insensitively. A value evaluating to null drops the key, the inherited value included. A value that evaluates to anything else but a string, or throws, fails that item: under on_item_error: fail the node fails before any child starts; under collect the item's entry in results is { "error": { "code", "message" } } and no child runs for it. A key outside the header-name grammar, two keys differing only in case, or a server-reserved key (session_id, actor_id, actor_external_id, calling_project_id) is rejected at write time with INVALID_TOOL_CONTEXT_KEY. Ignored for other node types.
intervalstringFor poll nodes — wait between attempts. Accepts a friendly suffix form (5s, 30s, 5m, 2h, 500ms) or ISO 8601 (e.g. PT5S).
fail_on_timeoutbooleanFor poll nodes — when max_iterations is reached without the exit condition becoming true, fail the run (true) instead of completing with condition_met=false (default false).
durationstringFor delay nodes — how long to wait. Accepts a friendly suffix form (5s, 30s, 5m, 2h, 500ms) or ISO 8601 (e.g. PT5S).
modereceiveFor webhook nodes — parks the run awaiting an inbound callback. receive is the only mode; to send a notification out of a graph, use an emit_event node instead.
event_typestringFor emit_event nodes — the internal event type to emit (e.g. guardrail.exception). The node's input_mapping becomes the event data. Any Webhook subscribed to this event type in the run's project then delivers it — signed, retried, and tracked by the Webhooks module — so the graph holds no URL or secret of its own.
orchestration_idstringPublic ID of the orchestration this node runs — the child orchestration for sub_orchestration nodes, and the orchestration run once per item for loop nodes.
max_iterationsintegerMaximum iterations before the node is aborted. For poll nodes this is the maximum number of attempts (default 10, ceiling 1000).
retryobjectRetry-on-failure policy. When the node throws a transient error (unexpected/infrastructure errors and upstream 5xx) and attempts remain, the run parks as sleeping and re-executes the node after the backoff delay. Terminal errors (4xx business errors) fail immediately. Absent or max_attempts <= 1 means fail-fast.

id and type are required; edges name nodes by id.

OrchestrationRun​

FieldTypeDescription
idstringPublic ID (run_...).
orchestration_idstringPublic ID of the parent orchestration.
orchestration_versioninteger, nullableThe orchestration version this run executes, fixed when the run started. Every later step of the run — the first drive, a wake from sleeping, a human or approval resume, a redrive after a crash — resolves the graph from this version, so editing the orchestration never re-shapes a run already in flight. Fetch the graph it names at GET /v1/projects/{project_id}/orchestrations/{orchestration_id}/versions/{version}. Null for runs created before pinning existed, which execute the live graph.
project_idstringPublic ID of the owning project.
statusqueued | running | sleeping | awaiting_input | completed | failed | cancelled | expiredRun lifecycle state. queued awaits a worker; running is actively executing; sleeping is parked on a delay/poll wait (no worker); awaiting_input is parked on a human node; completed/failed/ cancelled are terminal; expired is a wait that passed its deadline.
stateobjectCurrent accumulated state.
active_nodesstring[]Node IDs currently active.
artifactsobjectMap of node ID to output artifact.
errorobject, nullableWhy it failed, when status is failed.
trace_idstring, nullable
inputobject, nullableInitial input provided at run creation.
metadataobjectThe caller-owned key/value metadata supplied at run creation, returned verbatim. Absent when the run was started without any. The server writes nothing here and no key is reserved; the bag is never merged into state, so nothing in it reaches the graph.
idempotency_keystring, nullableThe deduplication key the run was started under, unique within the project and claimed for as long as the run record exists. Null for a run started without one, which every platform-started run is.
parent_orchestration_run_idstring, nullableThe run whose node started this one — set only on a child a loop or sub_orchestration node spawned, null for a run a caller started. A child is its own run with its own usage events, so this is what makes a delegated run's spend attributable to the run that ordered it.
parent_node_idstring, nullableThe node within parent_orchestration_run_id that started this run. Null when parent_orchestration_run_id is null.
orchestration_run_depthintegerloop / sub_orchestration edges between this run and the run a caller started: 0 for a caller-started run, one more than its parent's for a child. Starting a child past the effective bound — the smaller of the deployment's MAX_ORCHESTRATION_RUN_DEPTH (default 10) and the project's max_orchestration_run_depth — is refused with ORCHESTRATION_RUN_DEPTH_LIMIT, which fails the run that tried to descend. That bounds a graph whose sub_orchestration node names itself, directly or through a cycle of two graphs, which the intra-graph cycle check cannot see.
outputobject, nullableWhat a completed run returns: the orchestration's output_mapping evaluated over the final state, or, when it declares none, the terminal node artifacts keyed by node id. Null unless the run completed.
usageobjectWhat the run cost: token counts and cost_usd summed across every metered generation it produced and every run it started through loop / sub_orchestration nodes, at any depth. Present only on the single-run read (GET /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}); omitted from run lists and from every write's response, including a start with wait: true. A nested child is a run record of its own, so this figure spans several of them. Two consequences: summing usage across a list that mixes parents and children double-counts (filter with nested=false), and the per-event receipt at /v1/projects/{project_id}/usage/receipt stays scoped to one run — its line items carry a node_id from one graph only.
usage_ownobjectThe same roll-up restricted to this run's own nodes, excluding every nested run it started. Equal to usage for a run with no children; below it for a run that delegates. Present only on the single-run read, like usage. This is the field to read to see where cost sits in a run tree — own versus subtree — without walking the children.
required_actionobject, nullableWhy an awaiting_input run is parked. node_id, prompt and context describe a node's own pause and are present for every kind but paused, which is an operator pause with no node of its own and carries reason instead.
pause_requested_atstring (date-time), nullableWhen an operator pause was requested, or null when none is in force. Independent of status: a running run keeps running until its next checkpoint, and a run parked on a node keeps that node's required_action.
pause_reasonstring, nullableThe reason supplied with the pause, when one was.
started_atstring (date-time), nullable
completed_atstring (date-time), nullable
created_atstring (date-time)
updated_atstring (date-time)

id is the polling handle. required_action is what a parked run waits for: a human answer, an approval, or an operator pause. trace_id names the trace covering the run. metadata is not inherited by child runs.

Key Concepts​

Validate before you save​

POST /v1/projects/{project_id}/orchestrations/validate checks a graph without storing it and answers { valid, problems, warnings } — an edge pointing at a node that does not exist, an unreachable step, a node missing the field its type needs. Worth calling from a build step: a graph that cannot run is better caught before it is a version. Orchestrate several agents validates a three-agent pipeline before saving it.

Runs are background by default​

POST /v1/projects/{project_id}/orchestration-runs answers 201 with a queued run; poll GET /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id} until the status is terminal. Pass wait: true to hold the request open until the run settles or parks awaiting input. Orchestrate several agents starts one in the background and polls it to completed.

Retrying a run start is safe with an idempotency key​

A timeout on run start is ambiguous — the run may or may not have been created — and starting a run is the most expensive mutating POST in the API, because every node generates. idempotency_key on the request body, or the Idempotency-Key header, resolves it: the first request under a key starts the run and answers 201, and every later request carrying the same key answers 200 with that same run, whatever state it has since reached.

The key is claimed by the run record and stays claimed for as long as that record exists, so it never expires out from under a caller and lets a second run through. A retry that arrives while the original is still in flight gets the original run, not a second one.

Reusing a key with a different orchestration_id, input, tool_context or metadata is 409 IDEMPOTENCY_KEY_REUSED — a key names one request, so a caller that changed the body and kept the key has a bug. wait is not part of that comparison, so the same request may be retried blocking or non-blocking.

This is what a scheduled dispatcher needs to guarantee at most one run per slot: derive the key from the slot rather than from the attempt, and a retry can never double-charge.

A negative balance stops a run before it starts​

Every node generates, so POST /v1/projects/{project_id}/orchestration-runs answers 402 INSUFFICIENT_CREDIT and starts nothing while the project owes for usage already served — as do POST /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/resume and POST /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/human-input, which hand a paused run back to generate again. It is the project owner's balance. See A negative balance stops managed generation.

A Free account that has used its plan's monthly runs answers 403 PLAN_LIMIT_REACHED with resource: "runs" here as well, on its own credential too. See A plan's run allowance can stop generation.

This holds however the call arrives: a call to this API or an agent's tool call, for the start of a run, its resume and its human input.

Cancelling and pausing are never refused this way — stopping a run spends nothing.

A run already under way is paused instead, not refused. Its steps never pass through this API, so nothing can refuse them; what stops them is the reconciliation that discovers the debt, which pauses every run still driving — queued, running or sleeping — with a required_action.type of paused and a pause_reason saying to top up. The pause fans out to the run's loop and sub_orchestration descendants. Nothing is lost: the run keeps its checkpoint, and resuming it after a top-up re-drives from there — each parked descendant by its own id. A run already awaiting_input is left as it is, since it spends nothing until it is handed back.

A paused run tells you what it wants​

status: awaiting_input with required_action means a human or approval node is blocking — or, with required_action.type of paused, that an operator pause is, in which case reason says why and only resuming lifts it. Answer it with POST /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/human-input naming the node_id and the output, or nudge a run whose external condition has changed with POST /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/resume. POST /v1/projects/{project_id}/orchestration-runs/{orchestration_run_id}/cancel stops one that should not finish. Pause a run for a human decision parks a run on an approval node and settles it.

A run keeps the authority it started with​

A run stores the authority of whoever started it — the caller's key, or a trigger's policy_ids — and every node runs under it, after a resume or human input too: the member who hands a run back lends it nothing. A run whose starter no longer exists calls no tool: 409 WORK_AUTHORITY_MISSING. A child run that authority may not start fails its node with FORBIDDEN.

Nested runs and usage​

A loop node running N times, or a sub_orchestration node, starts child runs — each its own run record with its own usage events, parent_orchestration_run_id pointing back at the run that started it and parent_node_id naming which node did.

usage on a run is the cost of its whole subtree: every metered generation the run's own nodes produced, plus every run it started, at any depth. usage_own is the narrower figure — this run's own nodes only, excluding children — equal to usage for a run with no children.

This makes summing usage over a list of runs double-count: a parent and its children each report the same delegated spend. GET /v1/projects/{project_id}/orchestration-runs takes two filters to avoid it — nested=false returns only the runs a caller started directly (the set to sum usage over safely), and parent_orchestration_run_id returns one parent's own children, for reading the individual delegated runs behind its total. Passing both together is a 400.

Scoping tool_context into a child run​

A run started with tool_context (see tool context) hands its whole bag down to every child a loop or sub_orchestration node starts, by default — the behavior of every graph authored before context_keys existed. Setting context_keys on that node narrows what the child inherits to the listed keys, so a run holding a broad credential can delegate one step to a shared sub-graph without passing on what that sub-graph does not need; [] hands down nothing. Matching is case-insensitive, and the server-derived identity keys (session_id, actor_id, actor_external_id) are unaffected — a child re-derives them itself regardless of this list.

A loop node's item_tool_context gives each child keys of its own: each value is JSON Logic over { <item_variable>: <item>, "state": <run state> }, laid over the inherited bag; null drops the key. A value that is not a string, or throws, fails that item as on_item_error says. A naturali_ key is refused as in tool_context (400 INVALID_TOOL_CONTEXT_KEY, meta.keys), over REST, from a builtin call and in a formation alike.

A run's output is yours to shape​

Declare output_mapping and a completed run's output has the fields you name, however the graph is wired inside. Each key is an output field (a dotted key such as summary.title nests); each value is JSON Logic over { "state": <final run state> }, so run input (state.input), every state_mapping write and each node's artifact (state.nodes.<id>) are in reach.

{
"output_mapping": {
"summary": { "var": "state.summary" },
"answer": { "var": "state.nodes.answer.content" }
}
}

Renaming or adding a final node then changes nothing a caller reads. Without output_mapping, output is keyed by terminal node id. A missing path maps to null; a mapping that throws fails the run. It is versioned with the graph, so a run settles with the mapping of the version it started on. Branch an orchestration maps both the branch taken and the reply into output.

Versioning​

orchestration_version is stamped at start. Editing the definition archives the previous version — read it with GET /v1/projects/{project_id}/orchestrations/{orchestration_id}/versions, put it back with POST /v1/projects/{project_id}/orchestrations/{orchestration_id}/versions/{version}/restore — so an in-flight run is never rewired underneath itself. Pause a run for a human decision edits a graph this way, archiving version 1.

Who may do what​

Every route needs any project member.

Examples​

Validate a graph, then create it​

NODES='[{ "id": "triage", "type": "agent", "agent_id": "agent_V1StGXR8Z5jdHi6B" }, { "id": "notify", "type": "tool", "tool_id": "tool_V1StGXR8Z5jdHi6B" }]'
EDGES='[{ "from": "triage", "to": "notify" }]'

naturali validate-orchestration \
--project-id proj_V1StGXR8Z5jdHi6B \
--nodes "$NODES" \
--edges "$EDGES"

naturali create-orchestration \
--project-id proj_V1StGXR8Z5jdHi6B \
--name inbound-triage \
--nodes "$NODES" \
--edges "$EDGES"

Start a run and poll it​

naturali start-orchestration-run \
--project-id proj_V1StGXR8Z5jdHi6B \
--orchestration-id orch_V1StGXR8Z5jdHi6B \
--input '{ "ticket_id": "T-4471" }'

naturali get-orchestration-run \
--project-id proj_V1StGXR8Z5jdHi6B \
--orchestration-run-id orch_run_V1StGXR8Z5jdHi6B

Answer a run that is waiting on a person​

naturali submit-human-input \
--project-id proj_V1StGXR8Z5jdHi6B \
--orchestration-run-id orch_run_V1StGXR8Z5jdHi6B \
--node-id review \
--output '{ "decision": "approve" }'

Cancel a run​

naturali cancel-orchestration-run \
--project-id proj_V1StGXR8Z5jdHi6B \
--orchestration-run-id orch_run_V1StGXR8Z5jdHi6B