---
title: "Get a subtitle file"
method: GET
path: "/videos/{videoId}/subtitles/{lang}"
tags: ["Transcripts"]
---

# Get a subtitle file

`GET /videos/{videoId}/subtitles/{lang}`

## Request

- Base URL: `https://api.braiv.co/v1`
- URL: `https://api.braiv.co/v1/videos/{videoId}/subtitles/{lang}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Generates a temporary download URL for an SRT or WebVTT file in the requested source or translated language. Required scope: `transcripts:read`.

## Path parameters

- `videoId` string, required
- `lang` string, required: ISO-style language or locale code accepted by the underlying product.

## Query parameters

- `format` 'srt' | 'vtt': `srt` returns SubRip text; `vtt` returns WebVTT text.

## Response `200`

Subtitle file is ready.

- Subtitles
  - `status` 'ready', required: Confirms the subtitle artifact is ready.
  - `videoId` string, required: Parent library video ID.
  - `language` string, required: ISO-style language or locale code accepted by the underlying product.
  - `format` 'srt' | 'vtt', required: Returned subtitle serialization.
  - `downloadUrl` string, uri, required: Temporary subtitle file URL.

## Other responses

- `202`: Source transcription is still processing.
- `401`: A supported authentication header is missing or contains an invalid Public API key.
- `403`: Authentication succeeded, but the required scope, workspace role, or resource permission is missing.
- `404`: Video or requested subtitle file was not found.
- `422`: Transcription failed, so subtitles cannot be produced.
- `429`: The API key exceeded its allowed concurrency or request rate. Retry after in-flight work completes or the limit resets.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/braiv/apis/braiv-public-api.md) - [All operations](https://skmtc.dev/braiv/apis/braiv-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braiv/apis/braiv-public-api/revisions/8ed0fd0d0a6f?raw)