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:
- bash / zsh
- fish
- PowerShell
ADDON_ID="lifestyle-scene"
RUN_ID="replace-with-the-run-UUID"
set ADDON_ID "lifestyle-scene"
set RUN_ID "replace-with-the-run-UUID"
$env:ADDON_ID = "lifestyle-scene"
$env: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:
- bash / zsh
- fish
- PowerShell
curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/runs/$ADDON_ID/$RUN_ID?wait=15" \
-H "x-api-key: $GHOSTPULL_API_KEY"
curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/runs/$ADDON_ID/$RUN_ID?wait=15" \
-H "x-api-key: $GHOSTPULL_API_KEY"
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/orchestrator/runs/$env:ADDON_ID/${env:RUN_ID}?wait=15" `
-H "x-api-key: $env:GHOSTPULL_API_KEY"
status | What to do |
|---|---|
RUNNING | Call again. steps can contain progress and previews. |
SUCCEEDED | Read outputs; file outputs can have signed download links. |
FAILED, TIMED_OUT, ABORTED | Stop 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:
- bash / zsh
- fish
- PowerShell
curl --fail-with-body -N "$GHOSTPULL_URL/api/v1/orchestrator/runs/$ADDON_ID/$RUN_ID/stream" \
-H "x-api-key: $GHOSTPULL_API_KEY"
curl --fail-with-body -N "$GHOSTPULL_URL/api/v1/orchestrator/runs/$ADDON_ID/$RUN_ID/stream" \
-H "x-api-key: $GHOSTPULL_API_KEY"
curl.exe --fail-with-body -N "$env:GHOSTPULL_URL/api/v1/orchestrator/runs/$env:ADDON_ID/$env:RUN_ID/stream" `
-H "x-api-key: $env: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.