YouTube

Required

Fields required for a valid configuration.

Path	Type	Required	Description	Default	Constraints
required	object	Yes	Provide at least one of channels or video_urls (enforced at runtime).	—	no extra properties
required.channels	array	No	Channel URLs or handles to list videos from (e.g. https://www.youtube.com/@OpenAI or @OpenAI). At least one of channels/video_urls is required.	—	—
required.channels[]	string	No	—	—	—
required.video_urls	array	No	Explicit video watch URLs to scan (e.g. https://www.youtube.com/watch?v=dQw4w9WgXcQ). At least one of channels/video_urls is required.	—	—
required.video_urls[]	string	No	—	—	—

Masked

Sensitive fields under(secrets/credentials).

Path	Type	Required	Description	Default	Constraints
masked	object	No	Optional credentials. Leave empty for public videos.	—	no extra properties
masked.cookies	string	No	Netscape-format cookie file contents, used by yt-dlp to access age-restricted or members-only videos.	—	—

Optional

Optional configuration fields.

Path	Type	Required	Description	Default	Constraints
optional	object	No	—	—	no extra properties
optional.connection	object	No	Network controls for yt-dlp and transcript fetching.	—	no extra properties
optional.connection.ignore_errors	boolean	No	Continue past individual videos that fail to extract instead of aborting the run.	true	—
optional.connection.proxy_url	string	No	Optional HTTP/HTTPS/SOCKS proxy URL to mitigate rate-limiting when scanning at scale.	—	—
optional.connection.request_timeout_seconds	integer	No	Socket timeout for yt-dlp network operations.	30	min 1, max 300
optional.transcript	object	No	Transcript/caption fetching controls.	—	no extra properties
optional.transcript.languages	array	No	Preferred caption language codes in priority order (e.g. ["en"]). Empty means accept any available language.	—	—
optional.transcript.languages[]	string	No	—	—	—
optional.transcript.skip_transcript	boolean	No	When true, skip transcript fetching entirely (metadata-only assets, no detector content).	false	—

Extracted Metadata

Video

Field	Type	Required	Description
video_id	string	Yes	YouTube video id (11-char watch id)
title	string	Yes	Video title
channel_id	string	No	Channel id the video belongs to
channel_name	string	No	Channel/uploader display name
duration_seconds	integer	No	Video duration in seconds
view_count	integer	No	View count at extraction time
like_count	integer	No	Like count at extraction time
upload_date	string	No	Upload date (YYYYMMDD as reported by yt-dlp)
transcript_available	boolean	No	Whether a transcript/caption track was fetched
transcript_source	string	No	Origin of the transcript text: 'captions' (caption track) or 'whisper' (audio transcribed with faster-whisper)
transcript_language	string	No	Language code of the fetched transcript
transcript_is_generated	boolean	No	Whether the transcript is auto-generated (vs creator-uploaded)
caption_tracks	string[]	No	Available caption language codes

Examples

Brand channels transcript scan

Scan the latest videos from brand channels and run PII/secrets detection over English transcripts

Config Payload

{
  "type": "YOUTUBE",
  "required": {
    "channels": [
      "https://www.youtube.com/@OpenAI",
      "@AnthropicAI"
    ]
  },
  "optional": {
    "transcript": {
      "languages": [
        "en"
      ]
    }
  },
  "sampling": {
    "strategy": "AUTOMATIC",
    "rows_per_page": 25
  },
  "detectors": [
    {
      "type": "PII",
      "enabled": true
    },
    {
      "type": "SECRETS",
      "enabled": true
    }
  ]
}

Schedule

{
  "enabled": true,
  "preset": "weekday_morning",
  "cron": "30 7 * * 1-5",
  "timezone": "UTC"
}

Specific videos audit

Scan an explicit list of video URLs and process all of their transcripts

Config Payload

{
  "type": "YOUTUBE",
  "required": {
    "video_urls": [
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "https://www.youtube.com/watch?v=aqz-KE-bpKQ"
    ]
  },
  "sampling": {
    "strategy": "AUTOMATIC"
  },
  "detectors": [
    {
      "type": "PII",
      "enabled": true
    }
  ]
}

Random sampling via proxy

Randomly sample videos from a channel through a proxy to mitigate rate limiting

Config Payload

{
  "type": "YOUTUBE",
  "required": {
    "channels": [
      "https://www.youtube.com/@GoogleDevelopers/videos"
    ]
  },
  "optional": {
    "connection": {
      "proxy_url": "http://proxy.internal:8080",
      "request_timeout_seconds": 60
    }
  },
  "sampling": {
    "strategy": "AUTOMATIC",
    "rows_per_page": 50
  },
  "detectors": [
    {
      "type": "PII",
      "enabled": true
    }
  ]
}