---
title: "Index YouTube"
method: POST
path: "/v2/collections/{collection_name}/index/youtube"
tags: ["indexing"]
---

# Index YouTube

`POST /v2/collections/{collection_name}/index/youtube`

Index YouTube videos into a collection.

Three modes control how each video is processed and billed:

| mode | Behavior | Billing |
| --- | --- | --- |
| `transcript` (default) | Fetches the caption track (auto-generated or manual), formats it with inline timestamps, and indexes it as text. No frames or audio are processed. | Basic text pages (roughly 3 credits for an hour of captions) |
| `audio` | Pulls the audio track through the multimodal audio pipeline (transcription plus audio understanding). | 5 credits per audio minute |
| `video` | Pulls the video through the multimodal video pipeline (frame descriptions plus transcription). | 20 credits per video minute |

The default is `transcript` and will stay `transcript`: media modes cost orders of magnitude more for the same video and are strictly opt-in.

A video with no captions fails in transcript mode by default. Set `on_missing_transcript` to `audio` or `video` to fall back to a media mode for that video instead. Because the fallback changes what you are billed, it is recorded per video: `GET /v2/jobs/{job_id}` returns a `youtube` array with `mode_used`, `fell_back_from`, `transcript_available`, and `languages` for every video in the job.

Accepts either a single `url` string or a `urls` array (max 20; duplicate videos are removed). Supported URL shapes: `youtube.com/watch?v=`, `youtu.be/`, `youtube.com/shorts/`, `youtube.com/embed/`, `youtube.com/v/`, and `youtube.com/live/`. Redirects and shortener URLs are not followed. Live streams are not indexable, and media longer than 4 hours is rejected.

Headers:
- Authorization: Bearer {api_key} - Captain API key for authentication
- X-Organization-ID: Organization UUID
- Idempotency-Key: UUID for request deduplication (optional)

Returns:
    { job_id, status: "pending" }

## Path parameters

- `collection_name` string, required

## Headers

- `authorization` string, nullable

## Request body

- IndexYoutubeRequest
  - `custom_metadata` object, nullable — Custom metadata to attach to all indexed chunks. Keys must be strings. Values: str, int, float, bool, or List[str].
  - `languages` string[], nullable — Preferred transcript languages in priority order (ISO 639-1 codes). Defaults to English. Only specify if you need a non-English transcript (e.g., ['fr', 'de']). Falls back to auto-generated captions if manual transcript unavailable.
  - `url` string, nullable — A single YouTube video URL (youtube.com/watch?v=, youtu.be/, youtube.com/shorts/). Provide either 'url' or 'urls', not both.
  - `urls` string[], nullable — A list of YouTube video URLs to index. Provide either 'url' or 'urls', not both.
  - `mask_pii` boolean — When true, detected PII (emails, phone numbers, SSNs, credit cards, names, and locations) is masked in the parsed content before it is embedded and stored — replaced with entity tags like <PERSON> and <EMAIL_ADDRESS>. For images (including images embedded in PDFs), PII text visible in the image is also pixel-redacted. Opt-in; defaults to false, which leaves content unchanged.
  - `mode` 'transcript' | 'audio' | 'video' — How to index each video. 'transcript' (default): fetch the caption track and index it as text, billed as basic text pages. 'audio': pull the audio track through the multimodal audio pipeline, billed at 5 credits per audio minute. 'video': pull the video (frame descriptions plus transcription) through the multimodal video pipeline, billed at 20 credits per video minute. Media modes cost orders of magnitude more than transcript mode for the same video; the default is transcript and will not change.
  - `on_missing_transcript` 'fail' | 'audio' | 'video' — Only applies when mode='transcript'. What to do for a video whose captions are disabled or absent. 'fail' (default): that video fails. 'audio' / 'video': fall back to indexing that video through the corresponding media pipeline instead, billed at media rates. Any fallback is recorded per video in the job's youtube record (mode_used, fell_back_from) so the billing change is visible. Setting this together with a media mode is rejected with a validation error.

## Response `200`

Successful Response

- IndexJobResponse
  - `job_id` string, required
  - `status` string
  - `custom_metadata` object, nullable — The custom_metadata Captain accepted for this job, echoed back as validated. Null when none was supplied.

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runcaptain/api-reference/revisions/fe4649e3f4aa/schema)