Skip to main content

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:

  • 202 with a note: the run was stored, but its start was not confirmed. It may still start, so poll its run_id rather than start another.
  • 503 sim_runs_unavailable with a run_id: the run never started and reads as failed. 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.

statusMeans
queuedStored, waiting to start
runningUnder 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
doneFinished: items, declined, feed_cursor and deliveries are filled. See The shared response shape
failedStopped by an error, named in error
cancelledStopped 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.