Skip to main content
Running is two calls: start it, then poll it. There’s no synchronous “run and return the image” — execution is always asynchronous.

Start a run

POST /run with the deployment and its inputs:
Only deployment_id is required — inputs depends on what your graph expects. The response is immediate:
That means queued, not finished. Store the run_id.

Poll the run

GET /run with the run_id:
The run echoes back the inputs it actually received and the exact version that ran — invaluable when a result is wrong and you need to know whether the input or the graph was at fault.

Statuses

uploading is the one that trips people up. It means execution finished but outputs aren’t ready. Only success and failed are terminal — anything else means poll again.

Polling well

Guidelines that save trouble:
  • 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 failed as expected, not exceptional. Graphs fail on bad inputs; handle it.
  • Persist the run_id before you start polling. If your process restarts mid-run, that ID is the only way back to the result.
  • Back off on errors. A 500 while polling doesn’t mean the run failed — retry the poll.
For long runs, don’t hold an HTTP request open while polling. Store the run_id, return to your caller, and poll from a background job. Video-length graphs outlast most request timeouts.

Errors

More detail in Troubleshooting.

Concurrency

Nothing forces you to run one at a time — start several and poll each run_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.