<!-- Markdown twin of https://pixelvault.dev/docs/async-jobs/ -->

# Async jobs

Some work takes longer than a request should: describing an image, transcoding a social-ready video copy, transcribing video or audio, and building an export archive. PixelVault runs these as background jobs. Every one follows the same pattern:

1.  **Start** the job with a `POST`. The call returns immediately with the job state.
2.  **Poll** the resource that owns the job (the image, video, audio or export job), not the start endpoint, until the status is terminal.
3.  Or **subscribe** to the job's [webhook events](/docs/webhooks/) and skip polling.

```
curl -i -X POST https://api.pixelvault.dev/v1/videos/vid_abc123/enrich \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"

HTTP/1.1 202 Accepted
{ "data": { "id": "vid_abc123", "enrichment": { "job_id": "ven_abc123", "status": "pending" } } }
```

## The jobs

Job

Start

Poll

Status field

Job id

AI description

`describe=true` on [upload](/docs/api/images/#upload_image), or [`POST /v1/images/:id/describe`](/docs/api/images/#describe_image)

[`GET /v1/images/:id`](/docs/api/images/#get_image)

`description.status`

`dsc_` (webhooks only)

Social-ready video

`X-PixelVault-Social-Ready: true` on upload, or [`POST /v1/videos/:id/optimize`](/docs/api/videos/#optimize_video)

[`GET /v1/videos/:id`](/docs/api/videos/#get_video)

`social_optimization.status`

`vop_` (webhooks only)

Video transcript + storyboard

[`POST /v1/videos/:id/enrich`](/docs/api/videos/#enrich_video)

[`GET /v1/videos/:id`](/docs/api/videos/#get_video)

`enrichment.status`

`enrichment.job_id`, `ven_`

Audio transcript

[`POST /v1/audio/:id/enrich`](/docs/api/audio/#enrich_audio)

[`GET /v1/audio/:id`](/docs/api/audio/#get_audio)

`enrichment.status`

`enrichment.job_id`, `aen_`

Export archive

[`POST /v1/export`](/docs/api/exports/#start_export)

[`GET /v1/export-jobs/:id`](/docs/api/exports/#get_export_job)

`status`

`job_id`, `exp_`

## Statuses

Job

In progress

Terminal

Other values

Video optimization, video enrichment, audio enrichment

`pending`, `processing`

`complete`, `failed`

`not_requested`; optimization also `not_needed` when the original is already social-compatible

Export

`pending`, `processing`

`complete`, `failed`, `expired` (archive older than 24 hours)

AI description

`pending`

`done`, `failed`

`null` when never requested; a `pending` older than 2 minutes is reported as `failed` with `error: "describe_timeout"`

Failed video and audio jobs carry an `error` object with a safe `code` and `message`; a failed description carries an `error` string. Background workers retry video, audio and export jobs up to 3 times before marking them `failed`. Failed video and audio jobs return their reserved monthly seconds; a failed description is refunded unless it timed out.

## 200 vs 202

The video and audio start endpoints are idempotent and tell you where the job is by status code:

-   **202**: the job is queued or processing (newly queued, or already in flight). Poll.
-   **200**: the job is already complete, or (optimization only) the original is already compatible and no copy is needed. Read the result from the response.

Calling start again never queues a duplicate: it returns the current job. A `failed` job is retried by calling start again, which creates a new attempt with a new job id. `POST /v1/images/:id/describe` always answers `200`: an image that is already described or in progress returns its current state and uses no allowance; a failed one is retried. `POST /v1/export` answers `202`, or `409 export_in_progress` (with the active `job_id`) while another export for the project is running.

## Job failure codes

A job that fails in the background doesn't produce an HTTP error: the failure is stored on the resource you poll and sent in the `.failed` webhook. These codes therefore aren't on [Errors](/docs/errors/), which lists HTTP responses (including the ones a start call can return, such as `402 enrichment_limit_reached` or `503 optimization_unavailable`).

Job

Where

Code

Meaning

AI description

`description.error`

`describe_timeout`

The model didn't answer in time, or the job never reported back within 2 minutes. Not refunded.

`describe_failed`

The model call failed.

`describe_invalid`

The model answered with output that couldn't be parsed.

Social-ready video

`social_optimization.error.code`

`optimization_unavailable`

The transcoding service was temporarily unavailable.

`source_unavailable`

The original was no longer available (also used by video and audio enrichment).

`storage_limit_reached`

Storing the result would exceed the plan's storage quota (also used by enrichment).

`optimization_failed`

Transcoding failed.

`invalid_optimized_video`

The output was empty, incomplete, or failed H.264/AAC fast-start validation.

Video and audio enrichment

`enrichment.error.code`

`enrichment_unavailable`

The transcription service was temporarily unavailable.

`transcription_failed`

Speech-to-text failed.

`storyboard_failed`

Storyboard frames couldn't be extracted (video only).

`invalid_enrichment_output`

The generated transcript or storyboard didn't validate.

Export

`error` on the export job; `export.error.code` in the webhook

`export_failed`

The archive couldn't be built. The job's `error` field carries a message; start a new export.

Every code above can be retried by calling the start endpoint again, except `source_unavailable` (the original is gone) and `storage_limit_reached` (free storage or upgrade first). Video posters are generated during upload; if one is missing, [`POST /v1/videos/:id/poster`](/docs/api/videos/#generate_video_poster) retries it synchronously and answers `503 poster_unavailable` (temporary), `422 poster_too_large`, or `422 poster_generation_failed` when it can't.

## Poll with backoff and a deadline

Poll the owning resource with exponential backoff (start around 2 seconds, cap around 30), and give up locally after a deadline that suits your caller. A local timeout never cancels the server job: persist the asset id and job id and resume polling later. The CLI and SDK wait helpers implement exactly this (`waitForEnrichment` / `wait_for_enrichment`, `enrich-video --timeout`).

Example

Node.jsPython

```
const API = "https://api.pixelvault.dev/v1";
const headers = { Authorization: `Bearer ${process.env.PIXELVAULT_API_KEY}` };

// Start (or resume) the job. 202 = queued or running, 200 = already complete.
await fetch(`${API}/videos/vid_abc123/enrich`, { method: "POST", headers });

// Poll the asset, not the start endpoint, with backoff and a local deadline.
async function waitForEnrichment(id, timeoutMs = 600_000) {
  const deadline = Date.now() + timeoutMs;
  for (let delay = 2_000; Date.now() < deadline; delay = Math.min(delay * 2, 30_000)) {
    const res = await fetch(`${API}/videos/${id}`, { headers });
    const { data } = await res.json();
    const { status } = data.enrichment;
    if (status === "complete" || status === "failed") return data.enrichment;
    await new Promise((r) => setTimeout(r, delay));
  }
  return { status: "timeout" }; // the server job keeps running; poll again later
}

const enrichment = await waitForEnrichment("vid_abc123");
console.log(enrichment.status, enrichment.transcript?.vtt_url);
```

## Webhooks instead of polling

On Starter and Pro, subscribe an endpoint to the job's events and react when it finishes. Each job emits a `.completed` and a `.failed` event: `image.description.*`, `video.optimization.*`, `video.enrichment.*`, `audio.enrichment.*`, and `export.*`. Delivery is at least once, so keep polling as the fallback for a missed event. See [Webhooks](/docs/webhooks/).

## Next steps

-   [Video transcripts](/docs/guides/video-transcripts/) and [audio transcription](/docs/guides/audio/) end to end.
-   [AI descriptions & search](/docs/guides/ai-descriptions/).
-   [Export all media](/docs/guides/export-media/).
