> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legnext.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Task lifecycle

> Integrate Legnext's asynchronous submit, wait, and persist workflow safely.

Generation and follow-up endpoints are asynchronous. A successful submit returns
a task and `job_id`; it does not mean the media is ready.

The production flow is:

```text theme={null}
submit → persist job_id → poll or receive callback → reach a terminal state → save output
```

## Status values

| Status       | Meaning                                                  | Client action                                      |
| ------------ | -------------------------------------------------------- | -------------------------------------------------- |
| `pending`    | Accepted and waiting in a queue                          | Persist `job_id`; continue waiting                 |
| `staged`     | Queued behind the account's concurrency limit            | Continue waiting                                   |
| `processing` | Provider is generating the output                        | Continue waiting                                   |
| `retry`      | Legnext is resubmitting after a transient provider error | Continue waiting; do not create a replacement task |
| `completed`  | Output is available                                      | Save the output to durable storage                 |
| `failed`     | The task ended with an error                             | Inspect `error`; retry only when appropriate       |

`completed` and `failed` are terminal. Do not keep polling after either state.

## Polling

Poll [`GET /v1/job/{job_id}`](/api-reference/task-management/get-task). This
request does not require an API key: the UUID is a private capability token.

* Use a bounded wait and a non-zero interval; never tight-loop.
* Persist `job_id` before starting the wait.
* A client timeout does not cancel the server task. Resume polling the same
  `job_id` rather than submitting a replacement.
* Move long waits to a background job instead of holding an interactive HTTP
  request open.
* Keep the UUID out of browser URLs, analytics, and public logs.

A client timeout does not change the server task. It may complete after your
wait ends, so return a pending state to your application and let a worker resume
the same `job_id`.

## Webhooks

Generation endpoints accept an optional `callback` URL. Use it when your
application already has a durable background or event-processing architecture.

* Return a successful response quickly and process media asynchronously.
* Expect duplicate, delayed, or missing delivery and deduplicate by `job_id`.
* Treat the callback as a notification, then fetch the canonical task with Get
  Task before persisting the final state.
* Keep polling as a recovery path for a callback that never reaches your system.

Task callbacks do not currently provide a public signing secret. Keep the
callback endpoint behind an unguessable path, accept only the expected method
and content type, validate the payload shape, and rely on Get Task for the
canonical result.

Delivery timing and retries are not an exactly-once guarantee. Your handler must
be safe to run more than once.

## Retries and duplicate jobs

Legnext does not deduplicate submit requests by prompt. A repeated POST creates a
new billable task.

* Retry `429`, transient `5xx`, network failures, and timeouts with capped
  exponential backoff and jitter.
* Do not retry `400`, `401`, `402`, or `403` unchanged.
* If submit returned a `job_id`, poll that task instead of resubmitting.
* Use an application-level operation ID to prevent two workers from submitting
  the same user request.

If the submit connection fails before you receive a response, the outcome is
ambiguous: the server may already have created a task. Legnext does not expose a
client idempotency key, so your application must choose between risking a
duplicate task and asking the user or worker to retry.

See [Errors & Handling](/api-reference/errors) for failure classes and client
actions.

## Persist outputs

Remote output URLs are delivery URLs, not permanent application storage. Copy
completed media into storage you control before the retention window ends. See
[Output Storage](/getting-started/output-storage).