Async jobs and polling

How image, video, audio, and workflow operations complete.

Many generation and media operations return an identifier while work continues in the background. The exact response code and body depend on the endpoint; an accepted request is not necessarily a finished result. Poll the documented companion endpoint until it reaches a terminal state.

Generation and media tools commonly use the two patterns below. Assets and workflow runs have their own status contracts, described afterward.

Pattern 1 — task polling

Used where the background task’s return value is the answer: image generation, most image and video tools.

The submit response carries a task_id. Poll the task endpoint until status is terminal:

# 1. submit
curl -X POST https://api.simplified.com/api/v1/tools/remove-background \
  -H "Authorization: Api-Key $SIMPLIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/photo.jpg"}'
# -> 202 { "task_id": "9f2c..." }
# 2. poll
curl https://api.simplified.com/api/v1/tasks/9f2c... \
  -H "Authorization: Api-Key $SIMPLIFIED_API_KEY"
# -> { "status": "SUCCESS", "info": { ... result ... } }

status is terminal on SUCCESS or FAILURE. On failure, info carries the errors. A poll interval of 15–20 seconds is appropriate for most generation calls.

Pattern 2 — resource polling

Used where completion is written to a record by an external webhook, so the submit task only tracks the submission. Transcription and v2 video generation work this way.

Poll the resource, not the task, and read job_status:

curl https://api.simplified.com/api/v1/transcription/{id} \
  -H "Authorization: Api-Key $SIMPLIFIED_API_KEY"
# -> { "job_status": "DONE", ... }

job_status is terminal on DONE or FAILED.

For these endpoints a task_id may also be present, but it only tracks submission and will report success while the job is still running. Poll the resource.

Let the client handle polling

The CLI and the MCP server implement both patterns. In the CLI, use --wait on supported generation and editing commands to poll for a completed result. See job tracking for the matching status commands and waiting limits.

Assets and workflow runs

For asset ingestion, retrieve the asset and inspect status. Wait for 4 (done) before relying on finished file URLs; 2 and 3 indicate processing or thumbnail failure. See asset handling.

For workflows, keep the execution’s run ID and use the run-status endpoint. COMPLETED, FAILED, TERMINATED, and TIMED_OUT are terminal states; PAUSED is not completion. A definition ID and a run ID identify different resources.

A client timeout does not establish that server-side work was canceled. Check the existing job before submitting again, especially for generation or operations with external effects. MCP calls may also return before processing finishes; use the matching follow-up tool.