---
title: "List Captions"
method: GET
path: "/captions"
tags: ["Captions"]
---

# List Captions

`GET /captions`

## Request

- Base URL: `https://api.wistia.com/modern`
- URL: `https://api.wistia.com/modern/captions`
- Auth: HTTP bearer

Lists captions belonging to the account. Results can be narrowed to a specific media
with `media_id`, or to several media and languages at once with `media_ids[]` and
`languages[]`. Each caption includes its text, so combining these filters with
pagination fetches transcripts for many media in a few requests. Pass
`include=metadata` to omit transcript text when only track and language
information is needed.

## Requires api token with one of the following permissions
```
Read all folder and media data
```

Tokens with the "Act with a team member's permissions" permission
(`all:delegate_to_contact_permissions` scope) can also be used. Requests
made with such a token are authorized using the permissions of the
contact assigned to the token.

An [expiring access token](https://docs.wistia.com/reference/post_expiring-token)
created with the `all:delegate_to_contact_permissions` scope can also be
used. It lists only the captions of media it grants the `edit-transcripts`
permission on; no other permission reaches a media's captions.

## Query parameters

- `media_id` string
- `media_ids[]` string[]
- `languages[]` string[]
- `include` 'metadata'
- `page` integer
- `per_page` integer
- `cursor` object
  - `enabled` 0 | 1: If `cursor[enabled]` is set to 1, the first result set will be fetched with cursor pagination enabled. This values is ignored if `cursor[before]` or `cursor[after]` are set.
  - `before` string: If `cursor[before]` is set then cursor pagination is enabled and all records before the cursor up to the `per_page` are returned. This feature is useful for fetching "new records", for example, in a "pull to refersh" feature when showing records in a descending order.
  - `after` string: If `cursor[after]` is set then cursor pagination is enabled and all records after the cursor up to the `per_page` are returned.
- `sort_by` 'id' | 'created' | 'updated' | 'language'
- `sort_direction` 0 | 1

## Headers

- `X-Wistia-API-Version` string, required

## Response `200`

Captions retrieval successful

- object[]
  - `english_name` string: English name of the language.
  - `native_name` string: Native name of the language.
  - `language` string, required: A 3 character language code as specified by ISO-639–2.
  - `text` string, nullable: The text of the captions for the specified language in SRT format.
  - `is_draft` boolean, required
  - `id` string, required: The unique hashed identifier of the time-coded transcript.
  - `media_id` string, required: The hashed ID of the media the captions belong to.
  - `version` integer, nullable, required: The active caption payload version, or null when no payload is active.
  - `segments` object[], nullable, required: Time-coded caption cues when `include=segments`; null otherwise.
    - `start_ms` integer, required: The segment's start offset from the beginning of the media, in milliseconds.
    - `end_ms` integer, required: The segment's end offset from the beginning of the media, in milliseconds.
    - `text` string, required: The segment's transcript text.
  - `diarized_segments` object[]: Transcript text split at speaker-turn boundaries when `include=diarized_segments`. The media-level speaker timeline is shared across language tracks.
    - `start_ms` integer, required: The speaker-turn segment's start offset from the beginning of the media, in milliseconds.
    - `end_ms` integer, required: The speaker-turn segment's end offset from the beginning of the media, in milliseconds.
    - `text` string, required: Transcript text attributed to this speaker turn.
    - `speaker` object, required
      - `media_speaker_id` string, nullable, required: The media-specific speaker assignment identifier, or null for an unidentified turn.
      - `speaker_profile_id` string, nullable, required: The reusable account speaker-profile identifier, or null for an unidentified turn.
      - `detected_speaker_id` string, nullable, required: The anonymous detected-speaker identifier that can be assigned, or null once resolved or when unknown.
      - `display_label` string, required: The resolved name, a display-only generic label, or `Unknown speaker`. Speakers are numbered by when they first appear in the transcript. Assigning a name does not renumber the other speakers, so generic labels may start at `Speaker 2` or skip numbers. Use `detected_speaker_id` as the identifier.
      - `name` string, nullable, required: The assigned speaker profile's name, or null for an unidentified turn.
  - `diarization_status` 'ready' | 'processing' | 'unavailable' | 'disabled': Speaker-data availability when `include=diarized_segments`. Reading a derivable media with no speaker data starts generating it and reports `processing`; read again shortly for `ready`. `disabled` means the account has speaker identification turned off; an account owner or manager can turn it on in Account Settings.
  - `diarization_derivable` boolean: Whether speaker data can be generated from the active default transcript when `include=diarized_segments`. When false, the media stays `unavailable`.
  - `speaker_data_version` integer, nullable: The concurrency version for speaker assignments when `include=diarized_segments`, or null when speaker data is unavailable.
  - `cursor` string, nullable: A cursor for stable pagination based on current `sort_by` order. You can pass this to `cursor[before]` or `cursor[after]` as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with `cursor[enabled]`, or `cursor[before]` or `cursor[after]`.

## Other responses

- `400`: Bad request
- `401`: Unauthorized, invalid or missing token
- `404`: Media not found (when media_id parameter is provided)
- `500`: Internal server error

## Changes

- **2026-11-03** `b86cb2a7b420`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/wistia/apis/data-api/changes/captions/get.md)

---

[API](https://skmtc.dev/wistia/apis/data-api.md) - [All operations](https://skmtc.dev/wistia/apis/data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wistia/apis/data-api/revisions/b86cb2a7b420?raw)