# List productions

> Newest first. Pass `externalId` to find the production an earlier create with that id made (the same match a repeated create replays), for example to check whether a pull request already has one before sending its brief again. Every code file in each brief has `source` and `patch` emptied and carries `sourceOmitted: true`; read one production for its full files.

### GET /v1/productions

**List productions**

Newest first. Pass `externalId` to find the production an earlier create with that id made (the same match a repeated create replays), for example to check whether a pull request already has one before sending its brief again. Every code file in each brief has `source` and `patch` emptied and carries `sourceOmitted: true`; read one production for its full files.

Auth: `Authorization: Bearer rl_live_...` with the `productions` scope.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `workspaceId` | query | uuid | no |  |
| `stage` | query | string | no |  |
| `limit` | query | integer | no |  |
| `externalId` | query | string | no |  |

Responses:

| Status | Meaning |
| --- | --- |
| 200 | Productions, newest first. |
| 400 | Invalid request. |
| 401 | Missing, invalid or revoked key. |
| 403 | The key lacks the scope, or the key's owner has view-only access to the workspace (code `forbidden`). |
| 404 | Not found. |
| 429 | Rate limited, or a monthly cap reached. |

Response body (200):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `productions` | object[] | yes |  |
| `productions[].id` | uuid | yes |  |
| `productions[].workspaceId` | uuid | yes |  |
| `productions[].stage` | enum | yes | One of: `queued`, `writing_pitch`, `pitch_ready`, `greenlit`, `making`, `exporting`, `delivered`, `skipped`, `declined`, `cancelled`, `failed`. |
| `productions[].source` | object | yes |  |
| `productions[].source.kind` | enum | yes | One of: `app`, `api`, `mcp`. |
| `productions[].source.externalId` | string \| null | yes |  |
| `productions[].source.origin` | object \| null | no | Default `null`. |
| `productions[].source.origin.provider` | string | yes |  |
| `productions[].source.origin.label` | string | yes |  |
| `productions[].source.origin.url` | url \| null | no | Default `null`. |
| `productions[].source.origin.ref` | string \| null | no | Default `null`. |
| `productions[].source.origin.requestedBy` | string \| null | no | Default `null`. |
| `productions[].brief` | object | yes |  |
| `productions[].brief.intent` | string | yes |  |
| `productions[].brief.context` | string \| null | no | Default `null`. |
| `productions[].brief.media` | object[] | no |  |
| `productions[].brief.media[].id` | string | yes |  |
| `productions[].brief.media[].kind` | enum | yes | One of: `image`, `video`. |
| `productions[].brief.media[].url` | url | yes |  |
| `productions[].brief.media[].name` | string | yes |  |
| `productions[].brief.media[].description` | string \| null | no | Default `null`. |
| `productions[].brief.code` | object[] | no |  |
| `productions[].brief.code[].path` | string | yes |  |
| `productions[].brief.code[].source` | string | yes |  |
| `productions[].brief.code[].status` | enum \| null | no | One of: `added`, `modified`, `removed`, `renamed`. Default `null`. |
| `productions[].brief.code[].additions` | integer | no | Default `0`. |
| `productions[].brief.code[].deletions` | integer | no | Default `0`. |
| `productions[].brief.code[].patch` | string \| null | no | Default `null`. |
| `productions[].brief.code[].digest` | string \| null | no | Default `null`. |
| `productions[].brief.code[].score` | number | no | Default `0`. |
| `productions[].brief.code[].sourceOmitted` | boolean | no |  |
| `productions[].brief.format` | object | no |  |
| `productions[].brief.format.template` | enum | no | One of: `changelog`, `launch`, `feature`, `digest`, `custom`. Default `changelog`. |
| `productions[].brief.format.durationMs` | integer | no | Default `10000`. |
| `productions[].brief.format.aspect` | enum | no | One of: `16:9`, `4:3`, `3:2`, `21:9`, `1:1`, `9:16`, `3:4`, `2:3`, `4:5`. Default `16:9`. |
| `productions[].brief.format.sound` | object | no |  |
| `productions[].brief.format.sound.voiceover` | boolean | no | Default `true`. |
| `productions[].brief.format.sound.music` | boolean | no | Default `true`. |
| `productions[].brief.format.sound.sfx` | boolean | no | Default `true`. |
| `productions[].brief.brand` | object | no |  |
| `productions[].brief.brand.name` | string \| null | no | Default `null`. |
| `productions[].brief.brand.logoUrl` | url \| null | no | Default `null`. |
| `productions[].brief.brand.primaryColor` | string \| null | no | Default `null`. |
| `productions[].brief.brand.backgroundColor` | string \| null | no | Default `null`. |
| `productions[].brief.brand.fontFamily` | string \| null | no | Default `null`. |
| `productions[].brief.brand.tone` | string \| null | no | Default `null`. |
| `productions[].pitch` | object \| null | yes |  |
| `productions[].pitch.version` | integer | yes |  |
| `productions[].pitch.verdict` | enum | no | One of: `video`, `skip`. Default `video`. |
| `productions[].pitch.verdictReason` | string \| null | no | Default `null`. |
| `productions[].pitch.title` | string | yes |  |
| `productions[].pitch.summary` | string | yes |  |
| `productions[].pitch.shots` | object[] | yes |  |
| `productions[].pitch.shots[].index` | integer | yes |  |
| `productions[].pitch.shots[].title` | string | yes |  |
| `productions[].pitch.shots[].durationMs` | integer | yes |  |
| `productions[].pitch.shots[].beat` | string \| null | no | Default `null`. |
| `productions[].pitch.shots[].visual` | string | yes |  |
| `productions[].pitch.shots[].text` | string \| null | no | Default `null`. |
| `productions[].pitch.shots[].voiceover` | string \| null | no | Default `null`. |
| `productions[].pitch.shots[].mediaIds` | string[] | no |  |
| `productions[].pitch.shots[].codePaths` | string[] | no |  |
| `productions[].pitch.music` | string \| null | no | Default `null`. |
| `productions[].pitch.estimatedCredits` | integer | yes |  |
| `productions[].pitch.createdAt` | datetime | yes |  |
| `productions[].greenlight` | object \| null | yes |  |
| `productions[].greenlight.mode` | enum | yes | One of: `manual`, `auto`. |
| `productions[].greenlight.actor` | string | yes |  |
| `productions[].greenlight.actorName` | string \| null | no |  |
| `productions[].greenlight.at` | datetime | yes |  |
| `productions[].greenlight.pitchVersion` | integer | yes |  |
| `productions[].greenlightMode` | enum | yes | One of: `manual`, `auto`. |
| `productions[].delivery` | object \| null | yes |  |
| `productions[].delivery.shareUrl` | url | yes |  |
| `productions[].delivery.projectId` | uuid | yes |  |
| `productions[].delivery.editUrl` | url | yes |  |
| `productions[].delivery.exportId` | uuid | yes |  |
| `productions[].delivery.deliveredAt` | datetime | yes |  |
| `productions[].projectId` | uuid \| null | yes |  |
| `productions[].creditsCharged` | integer | yes |  |
| `productions[].error` | string \| null | yes | Why the production failed, in words you can show a person. Never the render machine's own diagnostics. |
| `productions[].createdAt` | datetime | yes |  |
| `productions[].updatedAt` | datetime | yes |  |
| `productions[].terminal` | boolean | no | True once the stage is one the production never leaves (delivered, skipped, declined, cancelled, failed, or a terminal stage added later). Stop polling when it is true; it is computed by the server, so it stays right for stages your client does not know yet. Absent from payloads stored before the field existed. |
| `productions[].pageUrl` | url | no | The production's page in the Raylight app. Absent from payloads stored before the field existed. |

Example (curl):

```bash
curl https://api.raylight.app/v1/productions \
  -H "Authorization: Bearer $RAYLIGHT_API_KEY"
```

## More

- Previous: [Overview](https://www.raylight.app/docs/reference.md)
- Next: [Create a production](https://www.raylight.app/docs/reference/post-v1-productions.md)
- All docs: https://www.raylight.app/llms.txt
- Everything in one file: https://www.raylight.app/llms-full.txt
- OpenAPI: https://api.raylight.app/v1/openapi.json