Job status

GET/creations/{id}

Every generation request returns a creation id — poll this endpoint to track it to completion. {id} accepts either the creation UUID or the task_id from the 202 response. Results are scoped to your account: an id that doesn't exist or belongs to someone else returns the same 404 ERR_NOT_FOUND.

poll.sh

curl https://api.rendergrid.io/api/public/v1/creations/c0ea4d5b-c965-4943-aaad-76fda0c53ca9 \
  -H "Authorization: Bearer rg_live_xxx"

Statuses

queued — accepted and waiting for a worker.
processing — generation is running.
completed — terminal; results are ready in result_urls.
failed — terminal; the charge has been refunded and error describes what happened.

Response fields

The response always contains id and status. While the creation is in progress, that's the whole body:

200 OK — in progress

{"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b", "status": "queued"}

{"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b", "status": "processing"}

result_urls (a list of output URLs) is present only when the creation is completed:

200 OK — completed

{
  "id": "c0ea4d5b-c965-4943-aaad-76fda0c53ca9",
  "status": "completed",
  "result_urls": [
    "https://cdn.rendergrid.io/images/2026/07/02/d13e03c7-7897-48b5-8571-8cd1e78e5f45/8b5f7dcb_20260702_100059_0f9a5d99_req_c0ea4d5b.jpg"
  ]
}

error is present only when it failed and is a sanitized, human-readable message — never raw provider output. A failed creation has already been refunded in full:

200 OK — failed

{
  "id": "…",
  "status": "failed",
  "error": "…a sanitized, human-readable reason…"
}

Polling rules

The minimum polling interval is 5 seconds per creation per API key — it is enforced server-side. Polling faster returns 429 ERR_RATE_LIMIT with a Retry-After header:

429 — polled too soon

HTTP/1.1 429 Too Many Requests
Retry-After: 2

{
  "error": {
    "code": "ERR_RATE_LIMIT",
    "message": "polled too soon — retry after the minimum interval",
    "details": { "min_interval_seconds": 5 }
  }
}

A robust poller sleeps 5 seconds between polls and, on any 429, honors Retry-After before trying again:

CREATION_ID="5b0214ae-9e39-460a-820a-f6ae3e24400b"
URL="https://api.rendergrid.io/api/public/v1/creations/$CREATION_ID"

while true; do
  HTTP_CODE=$(curl -s -o body.json -D headers.txt -w '%{http_code}' "$URL" \
    -H "Authorization: Bearer rg_live_xxx")
  if [ "$HTTP_CODE" = "429" ]; then
    RETRY=$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')
    sleep "${RETRY:-5}"
    continue
  fi
  STATUS=$(jq -r '.status' body.json)
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    cat body.json
    break
  fi
  sleep 5
done

At scale, prefer webhooks — we call you the moment the creation reaches a terminal status.