Sign in
indexing

Index YouTube

Index YouTube videos into a collection.

Three modes control how each video is processed and billed:

modeBehaviorBilling
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)
audioPulls the audio track through the multimodal audio pipeline (transcription plus audio understanding).5 credits per audio minute
videoPulls 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" }

post/v2/collections/{collection_name}/index/youtube

Path parameters

collection_namestring required

Headers

authorizationstring nullable

Request body

custom_metadataobject nullable

Custom metadata to attach to all indexed chunks. Keys must be strings. Values: str, int, float, bool, or List[str].

languagesstring[] 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.

urlstring nullable

A single YouTube video URL (youtube.com/watch?v=, youtu.be/, youtube.com/shorts/). Provide either 'url' or 'urls', not both.

urlsstring[] nullable

A list of YouTube video URLs to index. Provide either 'url' or 'urls', not both.

mask_piiboolean

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

Successful Response

job_idstring required
statusstring
custom_metadataobject nullable

The custom_metadata Captain accepted for this job, echoed back as validated. Null when none was supplied.

Changes

No recorded changes to this endpoint across all 1 revision of this API.