---
title: "List generations"
method: GET
path: "/v1/generations"
tags: ["Generations"]
---

# List generations

`GET /v1/generations`

## Request

- Base URL: `https://api.tryleap.ai`
- URL: `https://api.tryleap.ai/v1/generations`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Your workspace's generations, newest first, 50 to a page by default. Filter by model, status or where they were started. To read the next page, send `next_cursor` as `cursor` with the same filters.

Needs an API key with the `generations:read` scope.

## Query parameters

- `limit` string: Maximum number of rows to return: 1 to 100; default 50.
- `cursor` string: Send next_cursor as cursor; omit it for the first page.
- `model` string: Only runs of this model or preset. A preset's ID without a version, such as leap/headshot, takes in every version.
- `source` string: Only runs started from these places, comma-separated: api, mcp or studio, such as api,mcp.
- `status` string: Only runs in these states, comma-separated, such as queued,running.

## Response `200`

A page of generations.

- GenerationList: Forward list envelope. Live lists are not snapshots; totals are not promised.
  - `object` 'list', required: The list object discriminator.
  - `url` string, required: The list's resource path, such as /v1/records.
  - `data` Generation[], required: Resource objects in this page, in the requested order.
    - `id` string, required: The generation's ID, `gen_` and 24 letters and digits.
    - `object` 'generation', required
    - `model` string, required: The model or preset it runs, with a preset's version.
    - `modality` 'image' | 'video' | 'audio' | '3d' | 'text', required: What it makes: `image`, `video`, `audio`, `3d` or `text`.
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required: `queued`, then `running`, then one of `succeeded`, `failed` or `canceled`. Only `succeeded` is charged.
    - `provider` string, nullable, required: Which upstream ran it, once one did. Informational: the model ID and input stay the same whichever runs it.
    - `revision` string, required: The model's schema and price revision the run used.
    - `input` object, required: The input as it runs, with the defaults filled in.
    - `output` object[], required
      - `type` 'image' | 'video' | 'audio' | '3d' | 'text', required: What the file is: `image`, `video`, `audio`, `3d` or `text`.
      - `url` string, uri, required: A signed link to the file. Download what you keep: links expire after 24 hours, and reading the generation again signs fresh ones.
      - `expires_at` string, date-time, required: When `url` stops working, 24 hours after it was signed.
      - `content_type` string, required: The file's media type, such as `image/jpeg` or `video/mp4`.
      - `width` integer, nullable, required: Width in pixels; null for a sound.
      - `height` integer, nullable, required: Height in pixels; null for a sound.
      - `poster` object: For a video: a JPEG of a frame from its middle, about 720 pixels on the long side. Absent when none was made.
        - `url` string, uri, required: A signed link to the poster, which expires with the video's link.
        - `expires_at` string, date-time, required
        - `width` integer, required
        - `height` integer, required
    - `preview` object: While a preset that makes a still first is running: that still, once it exists, before the video it becomes. Absent for every other run, and for a run whose video also reads words or a photo you sent, such as a line to say or a photo the clip starts from: that still comes with the video. Also absent for the rest of a UTC day once 10 of the workspace's runs that showed one failed for their input.
      - `url` string, uri, required: A signed link to a smaller JPEG of the still, about 960 pixels on the long side. It works for 10 minutes; read the run again for a fresh one. The still itself comes with the finished run's output.
      - `expires_at` string, date-time, required
      - `width` integer, nullable, required
      - `height` integer, nullable, required
    - `error` object, nullable, required: Why a `failed` run failed, such as a refused prompt or a provider error; null otherwise. A failed run isn't charged.
      - `message` string, required
    - `failure_cause` 'provider_error' | 'provider_refused' | 'photo_blocked' | 'timeout' | 'outage' | 'input_removed' | 'input_rejected', nullable, required: What made a `failed` run fail, for a program to branch on: `provider_error`, `provider_refused` (the model's safety filter said no), `photo_blocked` (the photo check refused the photo), `timeout`, `outage` (the provider had a declared incident or could not serve Leap), `input_removed` (an input file was gone) or `input_rejected` (the provider couldn't use an input file: too small, an unreadable format, or no face). Null for any other run, and for a failure from before causes were recorded.
    - `usage` object, required: What the run cost your workspace.
      - `cost_usd` string, nullable, required: What the run cost, as an exact decimal string in US dollars; null until it's charged.
    - `source` 'studio' | 'api' | 'mcp', nullable, required: Where it was started: `api`, `mcp` or `studio`.
    - `batch_id` string, nullable, required: The batch it belongs to, `bat_...`; null if none.
    - `created_at` string, date-time, required: When it was created.
    - `started_at` string, date-time, nullable, required: When it started running; null while queued.
    - `completed_at` string, date-time, nullable, required: When it reached a final status; null before.
    - `slow_at` string, date-time, nullable, required: While a preset runs: when it counts as slow, one and a half times what Leap's runs of it take after `started_at`, scaled to this run's length, resolution and count. From then on a cancel works whatever the run has done, even once its `preview` shows. Null for any other run.
    - `deadline_at` string, date-time, nullable, required: While a preset runs: when Leap stops it if it hasn't finished, three times what Leap's runs of it take after `started_at`, scaled to this run's length, resolution and count, between 5 minutes (2 for a picture) and 12. It then fails with the `failure_cause` `timeout` and costs nothing. Null for any other run.
  - `has_more` boolean, required: Whether another page is available using next_cursor.
  - `next_cursor` string, nullable, required: Opaque next_cursor from the previous page. It works only for the list and filters it came from.

## Other responses

- `400`: `invalid_parameter`, `conflicting_credentials`
- `401`: `authentication_required`
- `403`: `permission_denied`
- `429`: `rate_limit_exceeded`

---

[API](https://skmtc.dev/tryleap/apis/leap-api.md) · [All operations](https://skmtc.dev/tryleap/apis/leap-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tryleap/apis/leap-api/revisions/c01f98d3e835?raw)