Long runs: start, poll and stop
A workflow run, an audit among them, takes longer than one request. POST /predictions answers at once with a run_id; read the run with GET /predictions?run_id= until its status is final; stop it early with POST /predictions/runs/{run_id}/cancel. The run keeps going on the server whether or not anything is reading it.
Start
curl --fail-with-body -sS -X POST -H "x-api-key: $CONSTELLATION_API_KEY" \
-H "content-type: application/json" "https://api.constellation.space/predictions" \
-d '{"workflow": "pass-yield", "from": "2026-11-10T00:00:00Z", "to": "2026-11-11T00:00:00Z"}'
{ "run_id": "run_20261109T101500_1a2b3c4d", "status": "queued" }
It needs a live key with workflows:write. The body's fields, the plan each run needs and every refusal are in Running and reading a workflow. Two answers need care:
202with anote: the run was stored, but its start was not confirmed. It may still start, so poll itsrun_idrather than start another.503 sim_runs_unavailablewith arun_id: the run never started and reads asfailed. Start it again.
Send an Idempotency-Key header (1 to 255 characters, such as a UUID per run you mean to start) so a retried or doubled request starts one run: the same key and body from the same account within 30 days answers 200 with the first run's run_id and its status now, and the same key with a different body is 409 idempotency_key_reused.
Poll
RUN=run_20261109T101500_1a2b3c4d
while :; do
status=$(curl -sS -H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/predictions?run_id=$RUN" | jq -r .status)
case "$status" in done|failed|cancelled) break ;; esac
sleep 5
done
echo "$status"
Reading needs predictions:read, and a run read is not counted as a prediction. Every live key on an account shares one rate limit budget, so poll every few seconds, not in a tight loop.
status | Means |
|---|---|
queued | Stored, waiting to start |
running | Under way; stage says where: finding passes, asking the snr model (or another lane's), computing lanes, running the graph, finishing the run, publishing to the feed, delivering to destinations |
done | Finished: items, declined, feed_cursor and deliveries are filled. See The shared response shape |
failed | Stopped by an error, named in error |
cancelled | Stopped by a person, with cancelled_by and cancelled_at |
Page a large run's items with page_records (1 to 5,000), following next_page with page.
To find a run started elsewhere, read the workflow: GET /predictions/workflows/{slug} carries active_run, its newest run still queued or running, or null. A run unsettled for more than a day is no longer listed there.
Read the newest result
GET /predictions?workflow=<slug> answers the workflow's newest finished forecast and never starts a run, so it takes no from, to or at (422 a_read_starts_no_run). With no finished run yet it answers 409:
{ "error": "no_finished_run", "workflow_version": 3, "detail": "POST /predictions starts a run of the workflow" }
as_of_utc reads the newest finished by an earlier time, or 404 no_run_as_of. workflow_version pins a version, and scenario_id a scenario.
Stop
curl --fail-with-body -sS -X POST -H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/predictions/runs/$RUN/cancel"
It answers the run with status: cancelled. A stopped run publishes nothing and sends nothing, and asking again answers the same stopped run. A run that already finished is 409 run_finished; one already publishing or sending is 409 run_delivering, because what it sent cannot be taken back. The Platform's Stop does the same.
When a newer run delivers first
When a newer run of the same workflow, version and kind (forecast or backtest) has finished or is delivering first, the older one delivers nothing and carries superseded_by with the newer run's id. Its items can still be read by run_id.
How long a run is kept
A run and its items are kept for 30 days; after that a read answers 410 run_data_expired, so run the workflow again. Connectors can pull each run's workflow results for 7 days.
Audits
An audit is a run of a workflow with a ledger step, over a past window, with "dataset": "audit". Upload the pass log first with POST /telemetry/pass-logs, which answers at once, then start, poll and read the audit like any run. On Explore, audit runs stop 48 hours after the first audit run (403 free_audit_ended); pass log uploads are never refused for the plan, and reports already run stay readable. See Audit passes against forecasts.