# List sessions

`GET /v2/live`

Your account's sessions, newest first, one page at a time.

Authentication: your API key in the `x-gladia-key` header.

## Parameters

- `limit` (query, integer, default: `20`, 1 to 100): Sessions per page, at most 100.
- `offset` (query, integer, default: `0`, 0 to 1000): Sessions to skip, at most 1000; past that, follow `next`.
- `cursor` (query, string): Where the next page starts: set in `next`, never by hand.
- `date` (query, string, date): Only the sessions created that day (`2026-10-12`).
- `after_date` (query, string, date-time): Only the sessions created after that date (ISO 8601).
- `before_date` (query, string, date-time): Only the sessions created before that date (ISO 8601).
- `status` (query, array of string): Only the sessions with these statuses (repeat it for several).
- `custom_metadata` (query, string): Only the sessions whose `custom_metadata` has these values: a JSON object (`{"user": "john"}`), or `custom_metadata[user]=john`.

## Responses

### 200

A page of sessions.

- `first` (string, required): URL of the first page.
- `current` (string, required): URL of this page.
- `next` (string, required): URL of the next page (it carries a `cursor`), `null` on the last page.
- `items` (array of object, required): The sessions, newest first.
  - `id` (string, required): Identifier of the session.
  - `request_id` (string, required): Identifier to quote to support.
  - `version` (2, default: `2`)
  - `status` (string, required, one of: `queued`, `processing`, `done`, `error`): `queued`: created, no WebSocket yet; `processing`: streaming (or dropped and still resumable); `done`: ended, the result is there; `error`: the session failed.
  - `created_at` (string, required): Creation date (ISO 8601, UTC).
  - `completed_at` (string, required): End date, once `done` or `error`.
  - `custom_metadata` (object, required): The init body's `custom_metadata`.
  - `error_code` (integer, required): `500` when the session failed, else `null`.
  - `kind` ("live", default: `"live"`)
  - `file` (object, required): The session's audio, once it ended.
    - `id` (string, required): Identifier of the session.
    - `filename` (string, required): Name of the recording, `null` when the audio was not recorded.
    - `source` (string, required): Download URL of the recording (`GET /v2/live/{id}/file`), `null` when not recorded.
    - `audio_duration` (number, required): Audio received, in seconds.
    - `number_of_channels` (integer, required)
  - `request_params` (object, required): The session's options, as validated.
  - `result` (object, required): The transcript, once `done`.
    - `metadata` (object, required)
      - `audio_duration` (number, required): Audio received, in seconds.
      - `billing_time` (number, required): Billed duration, in seconds.
      - `number_of_distinct_channels` (integer, required): Number of audio channels.
      - `transcription_time` (number, required): How long the session ran, in seconds.
    - `transcription` (object, required)
      - `languages` (array of string, required): Languages heard, in order of appearance.
      - `utterances` (array of object, required): Every final utterance, by start time.
        - `text` (string, required): The transcript. With named entity recognition or PII redaction on, it carries their inline elements (`<ner:name id="1">…</ner:name>`, `<pii:email id="1"/>`).
        - `start` (number, required): Start, in seconds from the start of the audio.
        - `end` (number, required): End, in seconds from the start of the audio.
        - `language` (string, required): Language spoken (ISO 639-1).
        - `confidence` (number, required): Confidence, from 0 to 1.
        - `channel` (integer, required): Audio channel the utterance was heard on, from 0.
        - `speaker` (integer, default: `null`): Speaker number, with `diarization`.
        - `words` (array of object, required): The words with their timestamps.
        - `text_raw` (string, default: `null`): The transcript without inline elements (with named entity recognition; never with PII redaction).
        - `entities` (array of object, default: `null`): The entities of the utterance, with named entity recognition or PII redaction.
        - `forced` ("max_duration", default: `null`): Set when the utterance was closed by `maximum_duration_without_endpointing` rather than by a pause.
      - `full_transcript` (string, required): The final utterances' text, joined.
    - `translation` (object, default: `null`): With `realtime_processing.translation`.
      - `success` (boolean, required)
      - `is_empty` (boolean, required): `true` when nothing was translated.
      - `exec_time` (number, required)
      - `error` (any, default: `null`)
      - `results` (array of object, required): One result per target language.
        - `error` (any, default: `null`): Always `null`.
        - `languages` (array of string, required): The target language of this result.
        - `full_transcript` (string, required): The translated text, joined.
        - `utterances` (array of object, required): The translated utterances, one per final.
        - `sentences` (array of any, required): Always empty.
        - `subtitles` (array of any, required): Always empty.
    - `messages` (array of any, required): The final transcript messages, as sent on the WebSocket.

```json
{
  "first": "string",
  "current": "string",
  "next": "string",
  "items": [
    {
      "id": "0199d7a2-5c3e-7b41-9f0a-3c2d1e4f5a6b",
      "request_id": "G-0199d7a2",
      "version": 2,
      "status": "queued",
      "created_at": "string",
      "completed_at": "string",
      "custom_metadata": {},
      "error_code": 0,
      "kind": "live",
      "file": {
        "id": "string",
        "filename": "string",
        "source": "string",
        "audio_duration": 0.5,
        "number_of_channels": 0
      },
      "request_params": {},
      "result": {
        "metadata": {
          "audio_duration": 0.5,
          "billing_time": 0.5,
          "number_of_distinct_channels": 0,
          "transcription_time": 0.5
        },
        "transcription": {
          "languages": [],
          "utterances": [],
          "full_transcript": "string"
        },
        "translation": {
          "success": false,
          "is_empty": false,
          "exec_time": 0.5,
          "error": null,
          "results": []
        },
        "messages": [
          null
        ]
      }
    }
  ]
}
```

### 400

The request is invalid: `validation_errors` lists why.

### 401

No API key, or an unknown one.

### 403

The key may not do this (its scopes, or the addresses it may be used from).

### 503

The service cannot answer right now: try again.

## Example

```bash
curl https://eu1.api.gladia.io/v2/live \
  -H "x-gladia-key: $GLADIA_API_KEY"
```