Statuses and IDs

Every status for generations, batches, workflow runs, uploads, capabilities and webhook endpoints, and every id prefix.

Read as Markdown

What 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
PrefixNamesWhere you see it
gen_One generationgeneration_id on every submit and read
bg_A batch: the takes from one variants submit on a video modelbatch_group_id, GET /batches/{id}
ast_An asset: upload, library file or outputasset_id, file fields in config
act_An actoractor_id
voc_A voicevoice_id
wf_A saved workflowworkflow_id, the invoke path
wfr_A workflow runworkflow_run_id, Location header on invoke
wh_A webhook endpointwebhook_id, DELETE /webhooks/{id}
whd_One webhook deliveryThe webhook-id header and the body's id. The same on every retry
bk_A brand kitbrand_kit_id in an MCP resource URI
prd_A product in a brand kitproduct_id in a brand kit resource
sk_live_An API keyShown once when created in the app. The API never returns it
whsec_A webhook signing secretShown 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.
Examples
kling_3_pro     capability id of Kling 3 Pro
ugc_face_cam    template key of Creator to camera

Id 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}$, or config is refused with invalid_config.

Generation status

StatusMeansStill running
queuedAccepted, not picked up yetyes
renderingBeing madeyes
post_processingOutput being copied to storageyes
completedEvery output delivered and storedno
failedDid not deliverno
  • There is no canceled status. A canceled job reads failed.
  • A failed generation carries error: { code, message }, and code can be null.
  • Loop on still_running, not on status: Wait for the result.
  • The final cost is credits_charged. It is null (not zero) until the charge is final. charge_summary says it in one sentence.

Batch status

Rolled up from every generation under one bg_ id.

StatusWhen
runningAny generation is not completed or failed
completedAll completed
failedAll failed
partialAll finished, some completed, some failed

Workflow run status

No wait endpoint for runs. Poll about every 30 seconds.

StatusMeansFinished
queuedRun created, nothing startedno
runningA step is workingno
completedEvery planned step finishedyes
partialSome steps finished, some failed, skipped or canceledyes
failedNothing finished, something brokeyes
canceledCanceled before any step completedyes
  • still_running is false on every finished status.
  • partial is normal: finished steps are charged, broken ones cost nothing.
  • waiting_approval is a valid status filter on the run lists, but no run uses it today.

Workflow node status

StatusMeans
pendingWaiting on an earlier step
readyInputs filled, starts next
dispatchingBeing submitted
runningGenerations working
completedDelivered
failedDid not deliver
skippedAn input failed, so it never ran
canceledRun 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_statususableDo
cleantrueUse the ast_ id
flaggedfalseNever usable. Upload another file
pendingfalseCall finalize again shortly

Branch on usable. Finalize is safe to repeat: Uploads.

Capability status

StatusMeans
availableSubmit now
requires_planNot in your plan. Carries required_plan
coming_soonNot live. Submits are refused
retiredDirect lookup only. Dropped from the list
unknownDirect 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

StatusMeans
activeReceiving events
failing3 deliveries in a row used every attempt. Still receiving
disabled20 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.

On this page