--- updatedAt: 2026-04-20T20:26:21.000Z agentTools: projectIndex: https://docs.wistia.com/llms.txt --- # List Captions by Media Lists captions belonging to a specific media. ## 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 and an authorization granting the `edit-transcripts` permission on this media can also be used. A token granted any other permission on the media lists no captions. # OpenAPI definition ````json { "openapi": "3.1.1", "info": { "title": "Data API", "description": "Wistia Data API", "version": "2026.09.0" }, "servers": [ { "url": "https://api.wistia.com/modern" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Captions" } ], "paths": { "/medias/{mediaHashedId}/captions": { "get": { "summary": "List Captions by Media", "x-speakeasy-group": "captions", "x-speakeasy-name-override": "list", "description": "Lists captions belonging to a specific media.\n\n## Requires api token with one of the following permissions\n```\nRead all folder and media data\n```\n\nTokens with the \"Act with a team member's permissions\" permission\n(`all:delegate_to_contact_permissions` scope) can also be used. Requests\nmade with such a token are authorized using the permissions of the\ncontact assigned to the token.\n\nAn [expiring access token](https://docs.wistia.com/reference/post_expiring-token)\ncreated with the `all:delegate_to_contact_permissions` scope and an\nauthorization granting the `edit-transcripts` permission on this media can\nalso be used. A token granted any other permission on the media lists no\ncaptions.\n", "parameters": [ { "name": "mediaHashedId", "in": "path", "description": "The hashed ID of the media for which captions are to be retrieved.", "required": true, "schema": { "type": "string" } }, { "name": "X-Wistia-API-Version", "in": "header", "required": true, "schema": { "type": "string", "default": "2026-09" } } ], "responses": { "200": { "description": "Captions retrieval successful", "content": { "application/json": { "schema": { "type": "array", "items": { "unevaluatedProperties": false, "type": "object", "properties": { "english_name": { "description": "English name of the language.", "type": "string" }, "native_name": { "description": "Native name of the language.", "type": "string" }, "language": { "description": "A 3 character language code as specified by ISO-639–2.", "type": "string" }, "text": { "description": "The text of the captions for the specified language in SRT format.", "type": [ "string", "null" ] }, "is_draft": { "type": "boolean" }, "id": { "description": "The unique hashed identifier of the time-coded transcript.", "type": "string" }, "media_id": { "description": "The hashed ID of the media the captions belong to.", "type": "string" }, "version": { "description": "The active caption payload version, or null when no payload is active.", "type": [ "integer", "null" ] }, "segments": { "description": "Time-coded caption cues when `include=segments`; null otherwise.", "type": [ "array", "null" ], "items": { "unevaluatedProperties": false, "type": "object", "properties": { "start_ms": { "description": "The segment's start offset from the beginning of the media, in milliseconds.", "type": "integer" }, "end_ms": { "description": "The segment's end offset from the beginning of the media, in milliseconds.", "type": "integer" }, "text": { "description": "The segment's transcript text.", "type": "string" } }, "required": [ "start_ms", "end_ms", "text" ] } }, "diarized_segments": { "description": "Transcript text split at speaker-turn boundaries when `include=diarized_segments`. The media-level speaker timeline is shared across language tracks.", "type": "array", "items": { "unevaluatedProperties": false, "type": "object", "properties": { "start_ms": { "description": "The speaker-turn segment's start offset from the beginning of the media, in milliseconds.", "type": "integer" }, "end_ms": { "description": "The speaker-turn segment's end offset from the beginning of the media, in milliseconds.", "type": "integer" }, "text": { "description": "Transcript text attributed to this speaker turn.", "type": "string" }, "speaker": { "unevaluatedProperties": false, "type": "object", "properties": { "media_speaker_id": { "description": "The media-specific speaker assignment identifier, or null for an unidentified turn.", "type": [ "string", "null" ] }, "speaker_profile_id": { "description": "The reusable account speaker-profile identifier, or null for an unidentified turn.", "type": [ "string", "null" ] }, "detected_speaker_id": { "description": "The anonymous detected-speaker identifier that can be assigned, or null once resolved or when unknown.", "type": [ "string", "null" ] }, "display_label": { "description": "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.", "type": "string" }, "name": { "description": "The assigned speaker profile's name, or null for an unidentified turn.", "type": [ "string", "null" ] } }, "required": [ "media_speaker_id", "speaker_profile_id", "detected_speaker_id", "display_label", "name" ] } }, "required": [ "start_ms", "end_ms", "text", "speaker" ] } }, "diarization_status": { "description": "Speaker-data availability when `include=diarized_segments`. Reading a derivable media\nwith no speaker data starts generating it and reports `processing`; read again shortly\nfor `ready`. `disabled` means the account has speaker identification turned off; an\naccount owner or manager can turn it on in Account Settings.\n", "type": "string", "enum": [ "ready", "processing", "unavailable", "disabled" ] }, "diarization_derivable": { "description": "Whether speaker data can be generated from the active default transcript when `include=diarized_segments`. When false, the media stays `unavailable`.", "type": "boolean" }, "speaker_data_version": { "description": "The concurrency version for speaker assignments when `include=diarized_segments`, or null when speaker data is unavailable.", "type": [ "integer", "null" ] }, "cursor": { "description": "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]`.", "type": [ "string", "null" ] } }, "required": [ "language", "is_draft", "id", "media_id", "version", "segments" ] } } } } }, "401": { "description": "Unauthorized, invalid or missing token", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "code": { "description": "A machine-readable identifier for the specific authorization failure.", "type": "string", "enum": [ "unauthorized_credentials", "account_inactive", "unauthorized_scope", "unauthorized_params" ] }, "error": { "type": "string", "examples": [ "Invalid credentials." ] } } } } } }, "404": { "description": "Media not found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Internal server error" ] } } } } } } }, "tags": [ "Captions" ], "x-readme": { "code-samples": [ { "name": "Typescript (SDK)", "language": "javascript", "code": "import { Wistia } from \"@wistia/wistia-api-client\";\n\nconst wistia = new Wistia({\n bearerAuth: process.env[\"WISTIA_BEARER_AUTH\"] ?? \"\",\n});\n\nasync function run() {\n const result = await wistia.captions.list({\n mediaHashedId: \"\",\n });\n\n console.log(result);\n}\n\nrun();" } ] } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "x-readme": { "samples-languages": [ "javascript", "shell", "node", "python", "ruby" ] } } ````