Skip to main content

Follow runs

Read a run's state and, when it succeeds, its outputs. These calls need runs:read and spend no credits.

Find the run IDs​

A run you started with the API answered with its runId and addonId. To find other runs of the account, call listOrchestratorRuns: it lists them newest first, each with its status as last recorded.

For a run started in the web app, open its page from Jobs and keep the URL. For a URL ending in /app/addon/?id=lifestyle-scene&run=<run UUID>, ADDON_ID is lifestyle-scene and RUN_ID is the value of run:

ADDON_ID="lifestyle-scene"
RUN_ID="replace-with-the-run-UUID"

Set the URL and key as in the quickstart.

Poll with a wait​

Call getOrchestratorRun with ?wait=15. It answers as soon as the run ends, or after 15 seconds with its current state:

curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/runs/$ADDON_ID/$RUN_ID?wait=15" \
-H "x-api-key: $GHOSTPULL_API_KEY"
statusWhat to do
RUNNINGCall again. steps can contain progress and previews.
SUCCEEDEDRead outputs; file outputs can have signed download links.
FAILED, TIMED_OUT, ABORTEDStop polling. Show message when present; keep error for programmatic handling.

Ended runs omit steps. A run belonging to another account, or an unknown run, answers 404. Download links expire; read the run again for fresh ones.

Stream instead of polling​

streamOrchestratorRun sends the same state as Server-Sent Events. Use curl's -N option to show events without buffering:

curl --fail-with-body -N "$GHOSTPULL_URL/api/v1/orchestrator/runs/$ADDON_ID/$RUN_ID/stream" \
-H "x-api-key: $GHOSTPULL_API_KEY"

Each event: state has a JSON data value matching getOrchestratorRun. The first state arrives immediately; later ones arrive when it changes. Lines starting with : are heartbeats, not state changes.

Stop when the state is terminal. The stream closes at the run's end or after 15 minutes. If it closes while the run is still running, reconnect; the first event is the current state. There is no need to replay old events. An already-open stream remains open after its key is revoked, until it closes.

Next​