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

# Jobs and statuses

> How a Director job moves from start to finish, what each field means, and every error the API returns

Every Director call that makes something (a shot, a film, a song, a plan) starts a **job**. You get the job back immediately, then poll it until it finishes. This page explains that loop. For each endpoint's fields, see the generated API reference.

## The loop

**1. Start**

`POST` a start endpoint. It answers **`202`** with a `director.job` and a `Location: /api/v1/director/jobs/{id}` header. The quoted credits are now held.

**2. Poll**

`GET /api/v1/director/jobs/{id}` every 10–30 seconds. Reading a job syncs it with the studio, so polling is what moves it along.

**3. Collect**

When `status` is `done`, the finished file is already in your Pixio assets. `output.url` is a signed link valid for 6 hours; `output.assetPath` is the durable copy.

```bash theme={null}
curl -s https://beta.pixio.myapps.ai/api/v1/director/jobs/$JOB_ID \
  -H "Authorization: Bearer $PIXIO_API_KEY"
```

> [!WARNING]
>
> On a timeout or a dropped connection, **keep polling the same job id**. Don't start the request again: a second start is a second job, held and billed on its own.

## Statuses

`status` is always one of these five values. Desktop and plugin clients branch on them, so no other value is ever returned.

| Status | Meaning | Final? |
| - | - | - |
| `queued` | Accepted, waiting to start (or being prepared) | No |
| `running` | Rendering, writing, sharpening or finishing. Also a film **waiting for storyboard approval** | No |
| `done` | Finished; `output` is set and credits are settled | Yes |
| `failed` | Stopped by an error; only finished parts were charged | Yes |
| `cancelled` | You cancelled it; only finished parts were charged | Yes |

`music/plan` and `prompts/write` (the writer calls) start as `running`; everything else starts as `queued`.

> [!NOTE]
>
> A film waiting for you to approve its storyboard stays `running`. Check `storyboard.waiting` rather than `status` or `stage` to know it needs you. See [Storyboards](https://support.myapps.ai/director-api/storyboards.md).

## The job object

```json theme={null}
{
  "id": "5b0c4f0e-8a51-4f8e-9a57-2d2f1b6f0c11",
  "object": "director.job",
  "endpoint": "videos/music",
  "status": "running",
  "stage": "3 of 4 parts done",
  "cancelRequested": false,
  "progress": 0.62,
  "etaSeconds": 240,
  "queue": { "ahead": 0, "estimatedCompletionAt": "2026-11-15T20:14:00Z" },
  "credits": { "quoted": 1055, "charged": 0 },
  "output": null,
  "parts": [
    { "index": 1, "label": "Section 1", "url": "https://beta.pixio.myapps.ai/api/v1/director/jobs/5b0c…/parts/1" }
  ],
  "deliverables": [],
  "versionJobIds": [],
  "versionOf": null,
  "qa": [{ "part": 1, "ok": true, "lipSync": 0.912, "borders": 0, "blendedFrames": 0, "fightStillShots": 0 }],
  "qaIssues": [],
  "faceFixJobId": null,
  "packageJobId": null,
  "result": null,
  "error": null,
  "details": null,
  "sourceJobId": null,
  "createdAt": "2026-11-15T20:00:00Z",
  "completedAt": null
}
```

| Field | What it tells you |
| - | - |
| `endpoint` | Which start endpoint made it, e.g. `videos/film`, `series/episodes` |
| `stage` | A plain-words step: `Preparing the shoot`, `Waiting to start`, `3 of 12 parts done`, `Rendering`, `Sharpening`, `Finishing the cut`, `Cancelling`, `Done`, `Cancelled`, `Stopped`. Show it to people; don't branch on it |
| `cancelRequested` | A cancel was accepted and lands at the end of the current render step |
| `progress` | 0 to 0.99 while working, exactly 1 when `done` |
| `etaSeconds` | Estimated seconds left, or `null` |
| `queue` | Only while waiting or rendering: `ahead` is how many jobs are in front of yours (0 once it renders). Only your own place is shown |
| `credits.quoted` | What was held when it started |
| `credits.charged` | What was settled. 0 until it finishes |
| `output` | When done: `{ type, url, assetPath, generationId }`. `type` is `video`, `image` or `audio` |
| `parts` | Music videos and films: each finished 15 s section or clip, playable before the whole job is done |
| `deliverables` | Packaging: the other frame shapes and cutdowns, each `{ index, name, aspect, cutdownSeconds, width, height, durationSeconds, url, assetPath }` |
| `pictures` | Films and music videos: every reference picture used, in `<Picture n>` order, `{ number, tag, designed, what, url }` |
| `qa` | Per-part checks: `lipSync` score, `borders`, `blendedFrames`, `fightStillShots` |
| `qaIssues` | With `visual_qa`: clones, extra faces, unwanted text, and for films with dialogue `speech_extra_words`, `speech_missing`, `speech_cut_off`, `speech_unscripted`. Notes only; re-shoot the part |
| `faceFixReport` | Face fixes: per section, `likenessBefore`, `likenessAfter`, `change`, `visible` (a change under 0.05 is not visible) |
| `faceFixJobId` | With `face_fix: "auto"`: the face-fix job that was started, billed on its own |
| `packageJobId` | A single shot sent with `brand_id` or `package`: the packaging job to poll for the branded video |
| `packageSkipped` | Why a requested packaging was not made (its hold was given back) |
| `durationShort` | Songs that came back shorter than asked: `{ requestedSeconds, actualSeconds }` |
| `versionJobIds` / `versionOf` | Films with `variants`: the other versions, and on each version the job it was made with |
| `storyboard` | Films with `storyboard: true`: `{ waiting, stills, url, sheetUrl }` |
| `result` | Writer calls only, once done: the plan or the written clips |
| `error` | A plain-words reason when it failed or was cancelled |
| `details` | Writer calls that failed: field-by-field reasons |
| `sourceJobId` | Redo, final, version and automatic jobs: the job it came from |

## Getting the files

| What | How |
| - | - |
| The finished file | `output.url` (6 hours), or `GET /director/jobs/{id}/video` (or `/image`, `/audio`) for a `302` to a fresh link. `409 conflict` until done; `404` if the job doesn't make that kind of file |
| One section or clip | `GET /director/jobs/{id}/parts/{n}`, `n` 1–28. Streams `video/mp4` with Range support, so it plays in a `<video>` tag. `404` until that part is ready |
| A reference picture | `GET /director/jobs/{id}/pictures/{n}`, `n` 1–40 |
| A packaging deliverable | `deliverables[].url`, or the copy at `assetPath` in your assets |

Finished files are copied into your Pixio assets, so they appear in your library and the regular asset endpoints work on them.

## Listing jobs

```bash theme={null}
curl -s "https://beta.pixio.myapps.ai/api/v1/director/jobs?limit=20&endpoint=videos/film" \
  -H "Authorization: Bearer $PIXIO_API_KEY"
```

Answers `{ object: "list", data: [...], hasMore, nextBefore }`, newest first. `limit` is 1–100 (default 20). For the next page pass `nextBefore` as `before`. An unknown `endpoint` filter is ignored, not an error.

> [!TIP]
>
> Listing does not refresh progress. Use it to find jobs; `GET` a single job for its live status.

## Cancelling

```bash theme={null}
curl -s -X DELETE https://beta.pixio.myapps.ai/api/v1/director/jobs/$JOB_ID \
  -H "Authorization: Bearer $PIXIO_API_KEY"
```

Answers `200` with the job. A cancel lands at the end of the current render step, so for a moment you'll see `cancelRequested: true` and stage `Cancelling` before `status` becomes `cancelled`. Finished sections or clips, plus any writing, are still charged. Cancelling a job that has already finished changes nothing.

## Free checks before you start

The shot, music-video and film endpoints take `?check=true` (or `?dry_run=true`); packaging and series episodes take `?dry_run=true`. Instead of starting, they answer **`200`** with a `director.preflight`: what would be made, the prompt-check report in `promptCheck`, and the quote in `credits.quoted` (plus `perVersion`/`versions` with `variants`, or `clip`/`packaging` for a packaged shot). Nothing is held or rendered.

`POST /director/prompts/check` checks prompts on their own, synchronously and free: `{ ok, issues[], counts }`.

## Errors

Every error body has `error` (a sentence to show) and `code` (a stable string to branch on), plus extra fields for some codes.

```json theme={null}
{ "error": "Insufficient credits", "code": "insufficient_credits", "requiredCredits": 1055 }
```

| Status | `code` | When | Extra fields |
| - | - | - | - |
| `400` | `invalid_json` | The body is not a JSON object or multipart form | |
| `400` | `invalid_request` | A field is missing or wrong, too many files, or text over its limit | `field`, `maxLength`, `length` for text limits; `details: [{ field, message }]` when the studio refused a value |
| `400` | `invalid_media_url` | A media URL couldn't be fetched, or an asset path isn't yours | |
| `401` | `missing_api_key` / `invalid_api_key` | No key, or a wrong or disabled key | |
| `402` | `insufficient_credits` | Not enough credits for the quote. Nothing started | `requiredCredits` |
| `404` | `not_found` | The job, brand, series, look or part isn't yours or doesn't exist | |
| `409` | `conflict` | A referenced job hasn't finished, the output isn't ready, or you already have 50 brands or 50 series | |
| `422` | `prompt_check_failed` | An official-format prompt has checker errors. Nothing was charged. Fix it, or send `strict_prompt=false` | `promptCheck: { issues: [{ level, message, clip }], counts }` |
| `429` | `concurrency_limit` | 8 Director jobs already queued or running | `Retry-After: 30` header |
| `500` | `internal_error` | Something unexpected. Nothing was charged | |
| `502` | `studio_error` | The studio couldn't start it. Nothing was charged | |
| `503` | `service_unavailable` | The studio is busy right now. Nothing was charged; retry shortly | |

> [!NOTE]
>
> When the studio refuses a request after Pixio has accepted it, the job is still recorded with status `failed` and error "Could not start.", and every hold is given back. You may see these in `GET /director/jobs`.

## Related

* [Billing and limits](https://support.myapps.ai/director-api/billing-and-limits.md) — what is held, what is charged, and when
* [Recipes](https://support.myapps.ai/director-api/recipes.md) — complete walkthroughs with curl
* [Director API overview](https://support.myapps.ai/integrations/director-api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.