Statuses and IDs
Every status for generations, batches, workflow runs, uploads, capabilities and webhook endpoints, and every id prefix.
Read as MarkdownWhat each id prefix names and what each status means. Each status list belongs to one kind of object.
Id prefixes
Prefix, underscore, then 32 lowercase hex characters. sk_live_ and whsec_ are secrets, not ids.
gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033
ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011| Prefix | Names | Where you see it |
|---|---|---|
gen_ | One generation | generation_id on every submit and read |
bg_ | A batch: the takes from one variants submit on a video model | batch_group_id, GET /batches/{id} |
ast_ | An asset: upload, library file or output | asset_id, file fields in config |
act_ | An actor | actor_id |
voc_ | A voice | voice_id |
wf_ | A saved workflow | workflow_id, the invoke path |
wfr_ | A workflow run | workflow_run_id, Location header on invoke |
wh_ | A webhook endpoint | webhook_id, DELETE /webhooks/{id} |
whd_ | One webhook delivery | The webhook-id header and the body's id. The same on every retry |
bk_ | A brand kit | brand_kit_id in an MCP resource URI |
prd_ | A product in a brand kit | product_id in a brand kit resource |
sk_live_ | An API key | Shown once when created in the app. The API never returns it |
whsec_ | A webhook signing secret | Shown once, in the answer to POST /webhooks. Never listed again |
Not prefixed:
- Capability id: a slug that names one model or tool. The list: Capabilities.
- Template key: a slug that names one workflow template. The list: Templates.
- Node id: set by the workflow author. Send back exactly what the API gave you.
kling_3_pro capability id of Kling 3 Pro
ugc_face_cam template key of Creator to cameraId rules
- Pass ids back exactly. Don't lowercase, trim, re-prefix or parse them.
- Never read an id out of a download URL. Use the body field.
- Asset ids must match
^ast_[0-9a-f]{32}$, orconfigis refused withinvalid_config.
Generation status
| Status | Means | Still running |
|---|---|---|
queued | Accepted, not picked up yet | yes |
rendering | Being made | yes |
post_processing | Output being copied to storage | yes |
completed | Every output delivered and stored | no |
failed | Did not deliver | no |
- There is no
canceledstatus. A canceled job readsfailed. - A
failedgeneration carrieserror: { code, message }, andcodecan benull. - Loop on
still_running, not onstatus: Wait for the result. - The final cost is
credits_charged. It isnull(not zero) until the charge is final.charge_summarysays it in one sentence.
Batch status
Rolled up from every generation under one bg_ id.
| Status | When |
|---|---|
running | Any generation is not completed or failed |
completed | All completed |
failed | All failed |
partial | All finished, some completed, some failed |
Workflow run status
No wait endpoint for runs. Poll about every 30 seconds.
| Status | Means | Finished |
|---|---|---|
queued | Run created, nothing started | no |
running | A step is working | no |
completed | Every planned step finished | yes |
partial | Some steps finished, some failed, skipped or canceled | yes |
failed | Nothing finished, something broke | yes |
canceled | Canceled before any step completed | yes |
still_runningisfalseon every finished status.partialis normal: finished steps are charged, broken ones cost nothing.waiting_approvalis a validstatusfilter on the run lists, but no run uses it today.
Workflow node status
| Status | Means |
|---|---|
pending | Waiting on an earlier step |
ready | Inputs filled, starts next |
dispatching | Being submitted |
running | Generations working |
completed | Delivered |
failed | Did not deliver |
skipped | An input failed, so it never ran |
canceled | Run canceled before it started |
A node error is { code, message }. code is one of provider_error, moderation, timeout, canceled, insufficient_credits, invalid_input, unknown.
Upload scan status
Returned by POST /uploads/{assetId}/finalize and POST /uploads/from-url.
scan_status | usable | Do |
|---|---|---|
clean | true | Use the ast_ id |
flagged | false | Never usable. Upload another file |
pending | false | Call finalize again shortly |
Branch on usable. Finalize is safe to repeat: Uploads.
Capability status
| Status | Means |
|---|---|
available | Submit now |
requires_plan | Not in your plan. Carries required_plan |
coming_soon | Not live. Submits are refused |
retired | Direct lookup only. Dropped from the list |
unknown | Direct lookup only. Id is not public |
A capability can leave GET /capabilities, and that is normal: Stability. A preset row in GET /presets uses the first three statuses.
Webhook endpoint status
| Status | Means |
|---|---|
active | Receiving events |
failing | 3 deliveries in a row used every attempt. Still receiving |
disabled | 20 in a row. Receives nothing until an owner or admin enables it in the app |
One 2XX puts a failing endpoint back to active. Webhooks.