---
title: "List events"
method: GET
path: "/v1/events"
tags: ["Events"]
---

# List events

`GET /v1/events`

## Request

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

Your workspace's events from the last 30 days, newest first, optionally only some types. Use it to catch up after your endpoint was down.

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.
- `type` string: Only events of these types, comma-separated, such as generation.succeeded,generation.failed.

## Response `200`

A page of events.

- EventList: 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` Event[], required: Resource objects in this page, in the requested order.
    - `id` string, required: The event's ID, `evt_...`, also sent as the `webhook-id` header. Skip any you've handled.
    - `object` 'event', required
    - `type` 'generation.succeeded' | 'generation.failed' | 'generation.canceled' | 'batch.completed' | 'webhook.test', required: What happened.
    - `api_version` string, required: The version of this payload's shape.
    - `created_at` string, date-time, required: When it happened.
    - `data` object, required
      - `object` union, required: What it happened to, as the API returns it when the event is sent: a generation, a batch for `batch.completed`, or the endpoint for `webhook.test`.
        - Generation: One run of a model or preset, with its status, its outputs and what it cost.
          - `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.
              - …
          - `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.
        - Batch: Up to 50 generations priced and held together, each run on its own.
          - `id` string, required: The batch's ID, `bat_...`.
          - `object` 'batch', required
          - `data` Generation[], required: Its generations, in the order you sent them.
            - `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
              - …
            - `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.
              - …
            - `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.
              - …
            - `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.
              - …
            - `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.
        - WebhookEndpoint: A URL your workspace's events are POSTed to.
          - `id` string, required: The endpoint's ID, `we_...`.
          - `object` 'webhook_endpoint', required
          - `url` string, required: Where Leap POSTs events.
          - `description` string, nullable, required: Your note, if any.
          - `events` string[], required: The event types it gets; ["*"] for every type, including types added later.
          - `disabled` boolean, required: Whether deliveries to it are stopped.
          - `disabled_reason` string, nullable, required: Why Leap disabled the endpoint, such as every delivery failing for 72 hours; null when it is on or you turned it off.
          - `created_at` string, date-time, required: When it was created.
          - `updated_at` string, date-time, required: When it last changed.
  - `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)