> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplified.com/api-reference/get-started/async-jobs-and-polling/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplified.com/_mcp/server.

# Async jobs and polling

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:

```bash
# 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`:

```bash
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`.

> **Warning**
>
> 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](/cli/install-and-authenticate) and the [MCP server](/mcp/overview) implement both
patterns. In the CLI, use `--wait` on supported generation and editing commands
to poll for a completed result. See [job tracking](/cli/use-from-an-ai-agent#track-asynchronous-work)
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](/mcp/assets-and-uploads).

For workflows, keep the execution's run ID and use the [run-status endpoint](/api-reference/workflows/runs/get-workflow-run-status). `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](/mcp/jobs-and-results).

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