> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/youtube.md).

# Youtube

YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags.

## Get YouTube channel details

> Returns channel details. Provide exactly one of \`id\`, \`handle\`, or \`channelUrl\`.\
> \
> \*\*Cost: 150 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeChannel":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"},"thumbnails":{"type":"string","format":"uri"},"isFamilySafe":{"type":"boolean"},"subscriberCount":{"type":"string"},"availableCountries":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"joinedAt":{"type":"string"},"viewCount":{"type":"string"},"videoCount":{"type":"integer"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/channel":{"get":{"operationId":"getYoutubeChannel","summary":"Get YouTube channel details","description":"Returns channel details. Provide exactly one of `id`, `handle`, or `channelUrl`.\n\n**Cost: 150 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"handle","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"channelUrl","in":"query","required":false,"schema":{"type":"string","minLength":10,"maxLength":1000,"format":"uri"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeChannel"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get videos for a YouTube channel

> Returns videos uploaded by the channel. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive).\
> \
> \*\*Cost: 150 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideo":{"type":"object","description":"Video result from search, hashtag, or trending endpoints.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"richThumbnail":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"publishDate":{"type":"string"},"views":{"type":"string"},"duration":{"type":"string"}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/channel/{id}/videos":{"get":{"operationId":"getYoutubeChannelVideos","summary":"Get videos for a YouTube channel","description":"Returns videos uploaded by the channel. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).\n\n**Cost: 150 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideo"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get shorts for a YouTube channel

> Returns shorts uploaded by the channel. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive).\
> \
> \*\*Cost: 150 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideo":{"type":"object","description":"Video result from search, hashtag, or trending endpoints.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"richThumbnail":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"publishDate":{"type":"string"},"views":{"type":"string"},"duration":{"type":"string"}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/channel/{id}/shorts":{"get":{"operationId":"getYoutubeChannelShorts","summary":"Get shorts for a YouTube channel","description":"Returns shorts uploaded by the channel. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).\n\n**Cost: 150 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideo"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get live streams for a YouTube channel

> Returns live streams (current and past) for the channel. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive).\
> \
> \*\*Cost: 200 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideo":{"type":"object","description":"Video result from search, hashtag, or trending endpoints.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"richThumbnail":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"publishDate":{"type":"string"},"views":{"type":"string"},"duration":{"type":"string"}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/channel/{id}/live-streams":{"get":{"operationId":"getYoutubeChannelLiveStreams","summary":"Get live streams for a YouTube channel","description":"Returns live streams (current and past) for the channel. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).\n\n**Cost: 200 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideo"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get YouTube video details

> Returns full metadata for a single video by its 11-character video \`id\`.\
> \
> \*\*Cost: 150 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideoDetail":{"type":"object","description":"Full video metadata returned by /youtube/video.","properties":{"type":{"type":"string"},"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"},"duration":{"type":"integer","description":"Length in seconds."},"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"keywords":{"type":"array","items":{"type":"string"}},"superTitle":{"type":"string"},"category":{"type":"string"},"isRatingsAllowed":{"type":"boolean"},"isLive":{"type":"boolean"},"isFamilySafe":{"type":"boolean"},"isPrivate":{"type":"boolean"},"isExclusive":{"type":"boolean"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/video":{"get":{"operationId":"getYoutubeVideo","summary":"Get YouTube video details","description":"Returns full metadata for a single video by its 11-character video `id`.\n\n**Cost: 150 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":5,"maxLength":20}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["shorts","video"]}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideoDetail"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get YouTube short details

> Returns full metadata for a single short by its video \`id\`.\
> \
> \*\*Cost: 200 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideoDetail":{"type":"object","description":"Full video metadata returned by /youtube/video.","properties":{"type":{"type":"string"},"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"},"duration":{"type":"integer","description":"Length in seconds."},"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"keywords":{"type":"array","items":{"type":"string"}},"superTitle":{"type":"string"},"category":{"type":"string"},"isRatingsAllowed":{"type":"boolean"},"isLive":{"type":"boolean"},"isFamilySafe":{"type":"boolean"},"isPrivate":{"type":"boolean"},"isExclusive":{"type":"boolean"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/shorts/{id}":{"get":{"operationId":"getYoutubeShorts","summary":"Get YouTube short details","description":"Returns full metadata for a single short by its video `id`.\n\n**Cost: 200 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":5,"maxLength":20}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideoDetail"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get comments on a YouTube video

> Returns top-level comments for a video. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive). \`sort\` is \`top\` (default) or \`latest\`.\
> \
> \*\*Cost: 10 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeComment":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"text":{"type":"string"},"likeCount":{"type":"string"},"replyCount":{"type":"string"},"publishedTime":{"type":"string"},"author":{"$ref":"#/components/schemas/YoutubeCommentAuthor"}}},"YoutubeCommentAuthor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnails":{"type":"string","format":"uri"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/comments":{"get":{"operationId":"getYoutubeComments","summary":"Get comments on a YouTube video","description":"Returns top-level comments for a video. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive). `sort` is `top` (default) or `latest`.\n\n**Cost: 10 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":5,"maxLength":20}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["top","latest"]}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeComment"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Search YouTube

> Search YouTube. \`mode\` selects what to search for (\`video\`, \`channel\`, or \`playlist\`). When \`mode=video\` results match \`YoutubeVideo\`; other modes return shape variants. Use \`cursor\` to paginate or \`maxItems\` for a one-shot bulk pull (mutually exclusive).\
> \
> \*\*Cost: 150 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideo":{"type":"object","description":"Video result from search, hashtag, or trending endpoints.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"richThumbnail":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"publishDate":{"type":"string"},"views":{"type":"string"},"duration":{"type":"string"}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","nullable":true},"hasNextPage":{"type":"boolean","nullable":true},"cursor":{"type":"string","nullable":true},"offset":{"type":"string","nullable":true,"description":"Numeric offset string for offset-paginated endpoints (e.g. Google Maps place search)."}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/search":{"get":{"operationId":"searchYoutube","summary":"Search YouTube","description":"Search YouTube. `mode` selects what to search for (`video`, `channel`, or `playlist`). When `mode=video` results match `YoutubeVideo`; other modes return shape variants. Use `cursor` to paginate or `maxItems` for a one-shot bulk pull (mutually exclusive).\n\n**Cost: 150 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"mode","in":"query","required":true,"schema":{"type":"string","enum":["video","channel","playlist"]}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["relevance","rating","upload_date","view_count"]}},{"name":"lang","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5}},{"name":"geo","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5}},{"name":"duration","in":"query","required":false,"schema":{"type":"string","enum":["short","medium","long"]}},{"name":"features","in":"query","required":false,"schema":{"type":"string","enum":["360","hd","subtitles","creative_commons","3d","live","purchased","4k","location","hdr","vr180"]}},{"name":"uploadDate","in":"query","required":false,"schema":{"type":"string","enum":["hour","today","week","month","year"]}},{"name":"maxItems","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideo"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get videos under a YouTube hashtag

> Returns videos tagged with \`tag\` from a single request.\
> \
> \*\*Cost: 150 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideo":{"type":"object","description":"Video result from search, hashtag, or trending endpoints.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"richThumbnail":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"publishDate":{"type":"string"},"views":{"type":"string"},"duration":{"type":"string"}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/hashtag":{"get":{"operationId":"getYoutubeHashtag","summary":"Get videos under a YouTube hashtag","description":"Returns videos tagged with `tag` from a single request.\n\n**Cost: 150 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"tag","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideo"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```

## Get trending YouTube videos

> Returns currently trending videos. Use \`geo\` to target a country (e.g. \`US\`, \`GB\`).\
> \
> \*\*Cost: 250 credits/request + 1 credit/item\*\*

```json
{"openapi":"3.0.3","info":{"title":"Pullbay API","version":"1.0.0"},"tags":[{"name":"youtube","description":"YouTube: channels, videos, shorts, live streams, comments, search, trending, hashtags."}],"servers":[{"url":"https://api.pullbay.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"YoutubeVideo":{"type":"object","description":"Video result from search, hashtag, or trending endpoints.","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":"string"},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"richThumbnail":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}},"channel":{"$ref":"#/components/schemas/YoutubeChannelRef"},"publishDate":{"type":"string"},"views":{"type":"string"},"duration":{"type":"string"}}},"YoutubeThumbnail":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"}}},"YoutubeChannelRef":{"type":"object","description":"Lightweight channel reference embedded in video or comment results.","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":"string"},"url":{"type":"string","format":"uri"},"subscriberCount":{"type":"string"},"badges":{"type":"array","items":{"type":"string"}},"thumbnails":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeThumbnail"}}}},"ErrorEnvelope":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"}}}}}}},"paths":{"/youtube/trending":{"get":{"operationId":"getYoutubeTrending","summary":"Get trending YouTube videos","description":"Returns currently trending videos. Use `geo` to target a country (e.g. `US`, `GB`).\n\n**Cost: 250 credits/request + 1 credit/item**","tags":["youtube"],"parameters":[{"name":"geo","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":5}}],"responses":{"200":{"description":"Successful request","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"integer"},"message":{"type":"string"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/YoutubeVideo"}},"pricing":{"type":"object","properties":{"creditsCharged":{"type":"number"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```