Skip to main content
Youtube endpoints live under /v1/youtube/*. See the API Reference for the full endpoint list. Credit rates are in Credits.

​
Pagination

Search, channel uploads, and comment endpoints return an opaque nextCursor. Pass it back unchanged on the next request.

​
Region (gl)

Optional gl selects the residential proxy region (default US). Allowed values are on GET /v1/youtube/regions (0 credits). hl is fixed to en and is not a public parameter. GET /v1/youtube/search takes q (required), optional cursor, and optional gl. Returns videos[] with canonical video objects and optional nextCursor. POST /v1/youtube/search accepts a JSON body { query, cursor?, gl? } with the same response shape. The Node SDK uses query for both search.list() and search.create() (GET maps to q on the wire). Both routes cost 5 credits per page. See Credits — Youtube.

​
Videos

GET /v1/youtube/videos/:id returns one video (10 credits). Shorts ids (/shorts/…) are accepted; responses use the watch URL shape. GET /v1/youtube/videos/:id/comments paginates with cursor (5 credits per page). Replies are not expanded in MVP. GET /v1/youtube/videos/:id/captions lists caption tracks (2 credits). GET /v1/youtube/videos/:id/transcript?lang= returns transcript segments (5 credits). Optional lang selects a track; omit to use the default. Credit rates for all video routes are in Credits — Youtube.

​
Channels

GET /v1/youtube/channels/:id accepts a channel id (UC…) or handle (@name). GET /v1/youtube/channels/:id/videos lists uploads with cursor pagination. GET /v1/youtube/channels/resolve?q= resolves a handle or search string to a channel (2 credits).

​
Reference

GET /v1/youtube/regions returns the allowed gl values (0 credits).

​
Not found

Missing video, channel, captions, or transcript returns HTTP 404 with NOT_FOUND. Upstream or parse failures return 503. Youtube does not expose granular soft-404 codes like Reddit or X — credits are still charged for definitive 404s on billed endpoints.

​
Watches

Youtube watches poll either search or channel uploads — provide query or channel (handle or id), not both. Both → HTTP 400. Interval: 60–3600 seconds. Cap: 20 active watches per Account. Each poll tick costs 5 credits. The first tick establishes a silent baseline (no events). Subsequent ticks emit video.created webhooks with the full video object. See Watches and Webhooks.