Skip to main content

​
Videos

Start with video details, then request only the deeper datasets your workflow needs.
  • GET /v1/providers/youtube/videos/{id} — core metadata
  • GET /v1/providers/youtube/videos/{id}/tracks — available transcript tracks
  • GET /v1/providers/youtube/videos/{id}/transcript?format=text|segments|words — compact text, timed segments, or timed words; omitting format preserves the rich words response
  • GET /v1/providers/youtube/videos/{id}/comments — paginated public comments
  • GET /v1/providers/youtube/videos/{id}/endscreen — end-screen links
The default comments request returns YouTube’s default-ranked page. Add all=true for a bounded newest-first collection, then inspect meta.partial and meta.warnings before treating it as complete. Video metadata lookups retry explicit YouTube bot challenges, with up to three processor attempts within one 120-second extraction budget. Transient errors use exponential backoff with jitter and honor upstream Retry-After. Retries visit the other processor before revisiting a slot. Recently challenged processors are deprioritized for 30 seconds within the same runtime isolate; this is a best-effort hint, not a global health guarantee. Switching processors does not guarantee a different outbound IP. Bot challenges are not cached as successful metadata and do not establish that a video is private or unavailable. If refresh fails and previously successful metadata exists, the response retains that data with freshness.state: "stale", its original freshness.fetchedAt timestamp in milliseconds, and freshness.reason: "UPSTREAM_UNAVAILABLE". Treat view counts as observations from that time. If no usable cached metadata exists, the lookup returns HTTP 503 with error code UNAVAILABLE. Genuine private and age-restricted video responses keep their availability metadata. A transcript can be requested directly without first fetching video metadata. The dashboard loads transcripts and metadata independently, renders each as it arrives, and preserves successful data when another request fails.

​
Channels

  • GET /v1/providers/youtube/channels/{id} — profile, public totals, links, and metadata
  • GET /v1/providers/youtube/channels/{id}/videos — paginated video catalog
  • GET /v1/providers/youtube/channels/{id}/playlists — paginated playlist catalog

​
Playlists

GET /v1/providers/youtube/playlists/{id} returns playlist metadata and its paginated video index. Fetching a playlist does not automatically fetch transcripts or comments for every video.
IDs, handles, and supported YouTube URLs are normalized by the provider pipeline, but hosted API path parameters should use the resource ID returned by discovery whenever possible.