Start a run
POST /run with the deployment and its inputs:
deployment_id is required — inputs depends on what your graph expects. The response is immediate:
run_id.
Poll the run
GET /run with the run_id:
Statuses
Polling well
- Poll every 1–3 seconds. Tighter than that is wasted requests; looser makes fast runs feel slow.
- Always set a timeout. A run that never reaches a terminal state must not hang your process forever.
- Treat
failedas expected, not exceptional. Graphs fail on bad inputs; handle it. - Persist the
run_idbefore you start polling. If your process restarts mid-run, that ID is the only way back to the result. - Back off on errors. A
500while polling doesn’t mean the run failed — retry the poll.
Errors
More detail in Troubleshooting.
Concurrency
Nothing forces you to run one at a time — start several and poll eachrun_id independently. Runs execute on machines, so throughput depends on available capacity rather than on your polling loop. If you’re firing a large batch, keep a bounded number in flight rather than launching hundreds at once.