# List requests

- **Method:** `GET`
- **Path:** `/v1/requests`
- **Operation ID:** `listRequests`
- **Tags:** Account

Lists your API requests, newest first. Pass `next_before` as `before` to get the next page, until it is null. A page can be empty while `next_before` is set, or hold more than `limit` requests made at the same moment.

## Effective servers

- `https://api.vcp.name`

## Authentication

- **bearer**: HTTP bearer (`API key`)

  An API key from Settings, starting vcp\_live\_.

## Query parameters

- **`limit`**: `integer`, default: `50`, minimum: `1`, maximum: `100`

  Requests per page.
- **`before`**: `string`, format: `date-time`

  Only requests made before this time.
- **`type`**: `string`, possible values: `"speech", "voice_design", "voice_clone", "voice_change", "transcription", "dub", "avatar_video", "cut"`
- **`status`**: `string`, possible values: `"queued", "running", "succeeded", "failed", "cancelled"`
- **`key_id`**: `string`, format: `uuid`

  Only requests made with this API key.

## Responses

### 200 OK.

**Content type:** `application/json`

schema: `RequestLog`, no additional properties

- **`next_before` (required)**: `string | null`, format: `date-time`

  Pass as before to get the next page, or null on the last page.
- **`requests` (required)**: `array`

  **Items:**

  schema: `RequestLogEntry`, no additional properties
  - **`api_key_id` (required)**: `string | null`

    The key that made the request, or null if the key was deleted.
  - **`created_at` (required)**: `string`, format: `date-time`

    When the job was created.
  - **`error` (required)**: `object | null`, schema: `ErrorDetail`, no additional properties

    Why the job failed, or null.
    - **`code` (required)**: `string`

      A code from the error tables.
    - **`message` (required)**: `string`

      What went wrong.
    - **`param`**: `string`

      The request field at fault, when there is one.
  - **`finished_at` (required)**: `string | null`, format: `date-time`

    When the job finished, or null while it runs.
  - **`id` (required)**: `string`

    Job id.
  - **`status` (required)**: `string`, possible values: `"queued", "running", "succeeded", "failed", "cancelled"`
  - **`summary` (required)**: `object`, schema: `RequestSummary`, no additional properties
    - **`description`**: `string`
    - **`model`**: `string`
    - **`text`**: `string`
    - **`voice`**: `string`
  - **`tokens_charged` (required)**: `integer | null`, minimum: `0`

    Tokens billed, or null until billing has run.
  - **`type` (required)**: `string`, possible values: `"speech", "voice_design", "voice_clone", "voice_change", "transcription", "dub", "avatar_video", "cut"`

**Example:**

```json
{
  "requests": [
    {
      "id": "04bd0571-e2c8-4d5b-a3cc-e56f85773abf",
      "type": "speech",
      "status": "succeeded",
      "error": null,
      "tokens_charged": 42,
      "api_key_id": "5f0c2a8e-3b1d-4c7e-9a62-1d8f4e7b2c90",
      "summary": {
        "text": "Hello from the API.",
        "voice": "Alloy",
        "model": "kokoro"
      },
      "created_at": "2026-10-30T00:10:42Z",
      "finished_at": "2026-10-30T00:18:01Z"
    }
  ],
  "next_before": null
}
```

### 400, 401, 403, 429, 500, 503

- `400` The request is invalid. The message names the field.
- `401` The API key is missing, invalid or revoked.
- `403` The account needs a paid plan, or the action is not allowed.
- `429` Too many requests. Retry after the Retry-After header.
- `500` Something went wrong on our side.
- `503` Temporarily unavailable. Retry after the Retry-After header.

**Content type:** `application/json`

schema: `ErrorBody`, no additional properties

- **`error` (required)**: `object`, schema: `ErrorDetail`, no additional properties

  *Schema `ErrorDetail` is shown above.*

**Example:**

```json
{
  "error": {
    "code": "invalid_request",
    "message": "text is required.",
    "param": "text"
  }
}
```

## Schemas

### ErrorBody

**Type:** `object`, no additional properties

*Schema `ErrorBody` is shown above.*

**Example:**

```json
{
  "error": {
    "code": "invalid_request",
    "message": "text is required.",
    "param": "text"
  }
}
```

- `ErrorDetail` — shown above.

### JobType

**Type:** `string`, possible values: `"speech", "voice_design", "voice_clone", "voice_change", "transcription", "dub", "avatar_video", "cut"`

### JobStatus

**Type:** `string`, possible values: `"queued", "running", "succeeded", "failed", "cancelled"`

- `RequestSummary` — shown above.
- `RequestLogEntry` — shown above.
- `RequestLog` — shown above.