Skip to main content

​
Running and polling

Only a published version runs. A workflow with no published version returns 404 no_published_version.

​
Start a run

An optional question may be supplied (max 1000 characters). It is a label only. The pinned subjects carry identity, and the question never changes what the run is about. Requires write:workflows.

​
Idempotency

Starting a run draws on your research usage allowance. Send an Idempotency-Key on every run request. A retry carrying the same key returns the original result rather than starting, and charging for, a second run. Without a key, a client that retries on a timeout spends twice. Treat the header as mandatory in any automated caller.

​
Usage and capacity

If the allowance cannot be reserved, the run does not start:
402 means the account’s allowance for the period is exhausted. 503 means the usage system itself was unreachable (details.reason of credit_policy_unconfigured or platform_unavailable). Retry the 503; the 402 will not clear until the allowance resets or the plan changes. Check the weight before committing by validating the definition. The estimate returned there is the same figure the run reserves against.

​
Poll a run

For a composition, the response expands the child runs and their per-node outputs, so you can see which step produced what rather than only the final state. Poll until the run reaches a terminal state.

​
List runs

Per workflow:
Across every workflow you own:
state accepts all (default), open and terminal.

​
Deliver and cancel

Both require write:workflows. Delivery is useful when a gate held a below-floor result and you have decided to release it anyway.

​
Ownership

Reading is visible to organisation members who can see the definition. Running, cancelling and delivering are owner-only: visibility does not grant the ability to spend.