Maak mijn eerste campagne
Menu van de documentatie
GET/api/v1/jobs/:id

Job status

Check a generation job or follow it live with SSE events.

Generating, correcting, adapting or translating is not instant: the API returns a job and the AI finishes it later. You can check its status whenever you want, listen to it live, or wait for the webhook. Requires the read permission (or any of the others).

Check the status

The status field is queued, running, succeeded, failed or canceled. When it finishes well, creativeId is the concept you can read with GET /api/v1/banners/:id and appUrl opens that concept in the app's studio. If it fails, error has a code and a message, and the credits are returned.

FieldWhat it is
id, type
The job id and its type: generate, edit, adapt or translate.
status
The job status.
creativeId, versionNo
The resulting concept and its version, once it finishes.
appUrl
Absolute link to the concept in the studio. null while it runs, if it failed, or with a test key.
error
null or the reason for the failure.
creditsCharged
Credits charged for the whole job (all sizes and locales).
createdAt, startedAt, finishedAt
Dates in ISO 8601 format.

Live events (SSE)

SSE (Server-Sent Events) is a stream of live notices over HTTP: you open the connection and the server sends you the progress.

The endpoint GET /api/v1/jobs/:id/events opens a text/event-stream stream. First it sends a status event with the current status and then, as it progresses, queued, running, progress (with step and pct) and finally succeeded or failed, and the server closes the stream.

  • The stream sends a heartbeat line (: ping) every 15 seconds to keep the connection alive.
  • It closes on its own after 5 minutes at most: reconnect or query GET /api/v1/jobs/:id.
  • If the job had already finished, you receive status and the stream closes.
  • A key without permission or a foreign id responds 401, 403 or 404 before the stream opens.
Opmerking. With a bm_test_ key, job_test_… ids already come as succeeded, with test: true and no credits charged.
Webhook eventsThe 13 events, all emitted today: when they fire, what the data field carries and an example of each.Get a bannerReads the spec, the current version, the pieces and the texts of a concept, or lists the concepts in your workspace.
Was deze pagina nuttig?