Statuses and ids

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

What each status means and each id prefix names. Each status list belongs to one kind of object. Don't mix them.

Id prefixes

Prefix, underscore, 32 lowercase hex characters.

gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033
ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011

Prefix	Names	Where you see it
`gen_`	One generation	`generation_id` on every submit and read
`bg_`	A batch: the generations from one submit with `variants`	`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
`sk_live_`	An API key	Shown once when created in the app. The API never returns it

Not prefixed:

Capability id: a slug, like actor_ultra, tts, veo_31. Capabilities.
Template key: a slug, like ugc_face_cam. Invoke takes the key.
Node id: set by the workflow author, like f_brand. Send back exactly what the API gave you.

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.
Another workspace's id answers not_found, never forbidden.
Asset ids must match ^ast_[0-9a-f]{32}$. Malformed in config: invalid_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 canceled status. A canceled job reads failed.
A failed generation carries error: { code, message }. code can be null.

Branch on still_running, not status

GET /generations/{id}/wait returns still_running. Loop until it is false. Looping on status can wait forever on a job stuck in post_processing. Results.

The final cost is in credits.credits_charged. It is null until credits.terminal is true. null is not zero.

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_running is false on every finished status.
partial is normal. Finished steps are charged. Broken ones cost nothing.

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.

`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 disappear from GET /capabilities. That is normal.

Statuses and ids

On this page