Skip to main content

​
Videos

Start with video details, then request only the deeper datasets your workflow needs.
  • GET /v1/videos/{id}?provider=youtube — core metadata
  • GET /v1/videos/{id}/tracks?provider=youtube — available transcript tracks
  • GET /v1/videos/{id}/transcript?provider=youtube&format=text|segments|words — compact text, timed segments, or timed words; omitting format preserves the rich words response
  • GET /v1/videos/{id}/comments?provider=youtube — paginated public comments
  • GET /v1/videos/{id}/endscreen?provider=youtube — end-screen links
The default comments request returns YouTube’s default-ranked page. Add all=true for up to five newest-first pages, about 100 comments. A crawl that reaches that limit returns what it collected with meta.partial: true and a warning, so inspect meta.partial and meta.warnings before treating it as complete. To read further, page with continuation; each page is a separate request. 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

Use a YouTube channel ID (UC followed by 22 letters, digits, underscores, or hyphens) or a handle with its leading @, such as @AltShiftX. A bare name such as AltShiftX returns HTTP 422 with code INVALID_ID and a message explaining the accepted formats. Validation runs before any credit reservation or provider request. The same rule applies to channel details, videos, and playlists.
  • GET /v1/channels/{id}?provider=youtube — profile, public totals, links, and metadata
  • GET /v1/channels/{id}/videos?provider=youtube — paginated video catalog
  • GET /v1/channels/{id}/playlists?provider=youtube — paginated playlist catalog

​
Playlists

GET /v1/playlists/{id}?provider=youtube 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.