# Generations

> List every queued generation your organisation has made, across all capabilities, and find one again by id — the way back to a lost id and to reconcile.

Every queued request — an image, a clip, a skybox, stored speech, a transcription — is a **generation** with a `gen_…` id. Each capability has its own poll (`GET /v1/images/{id}` and so on); `/v1/generations` is the one place that reads them all.

Use it to:

- **Recover an id you lost** — a crash between the 202 and storing the id, say.
- **Reconcile** — find everything still running, or everything that failed, since you last looked.
- **Show a history** across capabilities in one list.

```bash title="curl"
curl "https://api.lumavox.ai/v1/generations?status=running" \
  -H "Authorization: Bearer $API_KEY"
```

```json title="Response (abridged)"
{
  "data": [
    {
      "id": "gen_a1B2c3D4e5F6g7H8",
      "status": "running",
      "capability": "video",
      "prompt": "Waves rolling onto a black sand beach at dusk",
      "duration": 5,
      "resolution": "hd",
      "credits_micros": 25000000,
      "video": null,
      "error": null,
      "created_at": "2026-10-24T09:20:11.502Z",
      "finished_at": null
    }
  ],
  "next_cursor": null
}
```

Each item is the same object the capability's own poll answers, with every field — [Images](https://docs.lumavox.ai/media/images.md) shows them all, and [Queued jobs](https://docs.lumavox.ai/jobs.md) the statuses.

## List generations

`GET /v1/generations` returns your organisation's generations newest first, in flight or finished.

| Query | What it does |
|---|---|
| `limit` | Page size, 1–100. Default 30. |
| `cursor` | The `next_cursor` from the previous page. |
| `capability` | Only one capability: `image`, `video`, `tts` (stored speech), `stt` (transcription) or `skybox`. Anything else is a 422. |
| `status` | Only one state: `queued`, `submitted`, `running`, `succeeded`, `failed` or `moderated`. |

The answer is a page: pass each response's `next_cursor` back as `cursor` until it comes back `null` ([Conventions](https://docs.lumavox.ai/conventions.md#lists-and-pages)). A cursor this list did not give is a 422.

```bash title="curl"
curl "https://api.lumavox.ai/v1/generations?capability=image&status=failed&limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

Finished items carry a short-lived link to their file, made fresh on each response — as on every poll. The file itself stays in your [asset library](https://docs.lumavox.ai/library/assets.md).

### What a key sees

**The list shows only the capabilities your key holds.** A key with the `image` scope sees images; one with `tts` sees stored speech; the master key sees everything. Asking for a `capability` the key does not hold gives an empty page, not a 403 — and so does a key with no generation scope at all.

The scopes behind each capability:

| `capability` | Scope |
|---|---|
| `image` | `image` |
| `video` | `video` |
| `skybox` | `skybox` |
| `tts` | `tts` |
| `stt` | `stt` |

## Read one generation

`GET /v1/generations/{generation_id}` reads any capability's generation by id, in exactly the shape that capability's poll answers.

```bash title="curl"
curl https://api.lumavox.ai/v1/generations/gen_a1B2c3D4e5F6g7H8 \
  -H "Authorization: Bearer $API_KEY"
```

It is useful when you hold an id but not its capability. A generation made under a scope this key does not hold, one that belongs to another organisation, and one that does not exist are all the same 404.

## Reconciling

The pattern for a service that submits work and must not lose track of it:

1. **Store the `gen_…` id** from every 202 before doing anything else.
2. **Poll** each one on its capability's endpoint until it is terminal.
3. **On start-up, or on a schedule**, list `?status=queued`, `?status=submitted` and `?status=running` to pick up anything your process dropped, and `?status=failed` or `?status=moderated` to see what was refunded.

Every generation records what was asked for — `prompt`, size, `seed`, `folder_id`, `template_id` and the rest — and `credits_micros`, what was debited when it was accepted, as an integer of micro-credits ([Conventions](https://docs.lumavox.ai/conventions.md#credits)). A `failed` or `moderated` generation is refunded in full, and `error` says why.

## See also

- [Queued jobs](https://docs.lumavox.ai/jobs.md) — the statuses and the polling loop.
- [Assets](https://docs.lumavox.ai/library/assets.md) — the files the generations produced.
- [Credits and usage](https://docs.lumavox.ai/usage.md) — what was spent.
- [The generations reference](https://docs.lumavox.ai/reference/generations.md) — every field.