Get a video transcript
Caption reads use 4 credits per started 15 minutes. quality=premium is one read. An owned transcript answers 200 ready at no charge. Otherwise this call starts a Premium transcript of the whole video, 300 credits per started 15 minutes, using credits from the account's plan first and then the account's on-demand budget up to its limit, and answers 202 pending with the job and Retry-After until the transcript is ready. Read again after Retry-After; repeated reads join the same job and never charge twice. When the last Premium transcript for the video failed, the read answers 200 state failed with the job and last_attempt and charges nothing; retry=true starts a new one. When the plan or the budget blocks, 403 paid_plan_required (with unlock) or 402 quota_exceeded or spend_limit_exceeded carries the price in quote and nothing is charged. A default-premium account with nothing owned reads captions with a note. start/end only trim the returned content; language selects caption tracks, timestamps=false returns paragraphs. Premium lines carry speaker and index, and the body carries speakers and revision.
Request
- Base URL: https://api.arcmira.com
- URL: https://api.arcmira.com/v1/transcripts/{video_id}
- Auth: HTTP bearer
Path parameters
YouTube video id, 11 characters.
Query parameters
captions reads creator or automatic captions at 4 credits per started 15 minutes. premium is one read. An owned transcript returns 200 state ready at no charge. Otherwise the read starts a Premium transcript of the whole video, 300 credits per started 15 minutes, using credits from the account's plan first and then the account's on-demand budget up to its limit, and returns 202 state pending with the job until it is ready. When the last Premium transcript for the video failed it answers 200 state failed and starts a new one only with retry=true. 402 quota_exceeded or spend_limit_exceeded and 403 paid_plan_required carry the price in quote. It never substitutes captions. Default captions unless changed in account settings.
Comma-separated caption language priority list, at most 5, tried in order (e.g. "de,en"). Use asr for the first automatic track and asr-<code> for a specific one. Default en. languages[] in the response lists every track the video offers.
false returns paragraphs[] of { start, text, speaker? } instead of lines[], for reading rather than citing. Default true.
Window start in seconds from the beginning of the video. Send start and end together. On captions the window bills only its own started 15-minute blocks; on Premium it trims the returned content. An explicit Premium read is charged for the whole video from the account's plan credits and then its on-demand budget; a window does not reduce that charge.
Window end in seconds, greater than start and no greater than the video duration. Send start and end together.
Premium only; captions with retry=true returns invalid_query. When the last Premium transcript for this video failed, a read answers 200 state failed with the job and last_attempt and charges nothing; retry=true starts a new one under the same quote, budget and one-job-per-video rules as the first read. While that refund is still settling (job.status refund_pending) even retry=true answers state failed. Without a failed job it changes nothing.
Captions only; Premium with refresh=true returns invalid_query. Refetch the caption track from YouTube instead of serving the stored copy. Available only for videos outside our index; a pipeline-owned video refuses it with invalid_query.
The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client.
Response
state ready: the transcript (video, quality, source, language, languages, lines or paragraphs, speakers and revision on Premium, rows_billed, as_of, note). state failed (Premium only): the last Premium transcript for this video failed; job and last_attempt say why, nothing was charged, and retry=true starts a new one.
Example response
{
"video": {
"id": "dQw4w9WgXcQ",
"title": "TBPN | Tuesday, August 4",
"channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
"channel_name": "TBPN",
"published_at": "2026-08-04T17:00:00.000Z",
"duration_seconds": 10800,
"watch_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
},
"quality": "captions",
"source": "creator_captions",
"language": "en",
"languages": [
{
"code": "en",
"name": "English",
"generated": false
}
],
"lines": [
{
"start": 4787,
"end": 4791.5,
"text": "Ramp has been on the show for a while now."
},
{
"start": 4791.5,
"end": 4796,
"text": "The pitch is still the same, spend less time on expenses."
}
],
"rows_billed": 12,
"as_of": "2026-08-04T18:12:00.000Z",
"note": "This transcript is the video's own caption track. `creator_captions` were written or approved by the channel; `third_party_quick` are YouTube's automatic captions and can misspell names and drop punctuation. `language` says which track you got."
}Changes
No recorded changes to this operation across all 1 revision of this API.