Async jobs & polling

Generation on Layer is asynchronous. Both direct model runs (forge) and workflow runs return immediately with 202 Accepted and a run identifier; you then poll for the result.

Lifecycle

Submit — POST to an execute endpoint. The response includes an id, an initial status, and poll_interval_seconds (currently 10).
Poll — GET the run by id every poll_interval_seconds until it reaches a terminal status.
Read — on success, read the outputs; on failure, read error / error_code.

# Submit
curl -X POST https://api.app.layer.ai/api/v1/workspaces/$WORKSPACE_ID/inferences \
  -H "Authorization: Bearer $LAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model_id": "MODEL_ID", "parameters": { "prompt": "a mossy stone golem" } }'
# → { "inference_id": "…", "status": "IN_PROGRESS", "poll_interval_seconds": 10 }

# Poll
curl https://api.app.layer.ai/api/v1/workspaces/$WORKSPACE_ID/inferences/INFERENCE_ID \
  -H "Authorization: Bearer $LAYER_TOKEN"

Forge (single model) runs

POST .../inferences returns an inference_id. Poll GET .../inferences/{id}.

Status	Terminal	Meaning
`IN_PROGRESS`	no	Running.
`COMPLETE`	yes	Done — response includes `outputs[]` and `actual_price_creative_units`.
`FAILED`	yes	Failed — response includes `error` and `error_code`.
`CANCELLED`	yes	Cancelled.
`DELETED`	yes	The run was deleted.

Workflow runs

POST .../workflows/{id}/runs returns a run_id. Poll GET .../workflows/{id}/runs/{run_id}. The response includes a per-step steps[] array (each with name, status, and error/error_code), so you can see where a run is or why it failed.

Status	Terminal	Meaning
`PENDING`	no	Queued.
`RUNNING`	no	Executing.
`SUCCESS`	yes	Done — response includes outputs.
`FAILURE`	yes	Failed — see `steps[]` for the failing step.
`CANCELLED`	yes	Cancelled.

Cancellation

The REST API does not expose a cancel endpoint. A run can be cancelled from the Layer app, or via the MCP server (cancel_workflow_run), which releases any reserved Creative Units.