---
title: "Get one cache-first transcript"
method: GET
path: "/v1/transcript"
tags: ["Transcripts"]
---

# Get one cache-first transcript

`GET /v1/transcript`

## Request

- Base URL: `https://api.scripthaul.com`
- URL: `https://api.scripthaul.com/v1/transcript`
- Auth: HTTP bearer

Use exactly one query mode: video_id starts or reads a transcript; request_id polls an earlier 202 response. The two parameters are mutually exclusive. A cache hit costs 0 credits and a cold delivery 1. With translate=true, when YouTube declines to translate the captions, the transcript is delivered in the requested language for 300 credits per started 10,000 characters of transcript (at most 1,500), on top of the delivery credit, labelled translation: served; nothing extra is charged when it cannot be delivered.

## Query parameters

- `video_id` string
- `format` 'json' | 'clean' | 'timestamped' | 'both' | 'srt' | 'vtt' | 'md'
- `language` string
- `fallback` boolean
- `raw` boolean
- `fresh` boolean
- `translate` boolean
- `request_id` string, uuid

## Response `200`

Transcript

- Transcript
  - `ok` unknown, required
  - `video` object, required
    - `id` string, required
    - `title` string, nullable
    - `channel` object
      - `id` string, nullable
      - `title` string, nullable
    - `published_at` string, nullable
    - `duration` integer, nullable
  - `language` Language, required
    - `requested` string, required
    - `delivered` string, required
    - `kind` 'manual' | 'asr', required
    - `fallback` boolean, required
    - `translation` 'not_requested' | 'served' | 'refused' | 'unavailable', required: refused: the translation throttle declined this attempt and the source track was delivered (retry later). unavailable: the video offers no translation into the requested language. Job rows are null before delivery.
  - `format` string, required
  - `text` string
  - `cues` object[]

## Other responses

- `202`: Still fetching; poll the returned URL
- `400`: Typed API error
- `401`: Typed API error
- `402`: Typed API error
- `403`: Typed API error
- `404`: Typed API error
- `410`: Typed API error
- `429`: Typed API error
- `502`: Typed API error
- `503`: Typed API error

---

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