# Social Fetch API - YouTube endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

12 documented YouTube operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/youtube/channel
Get YouTube channel
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/channel/get.mdx
SDK: client.youtube.getChannel({ handle })
Parameters:
- channelId (optional, string) - Optional YouTube channel id for the request.
- handle (optional, string) - Optional YouTube channel handle for the request.
- url (optional, string) - Optional YouTube channel URL for the request.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/youtube/channel?url=https://www.youtube.com/@MrBeast" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/channels/videos
List YouTube channel videos
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/channels/videos/get.mdx
SDK: client.youtube.getChannelVideos({ handle })
Parameters:
- channelId (optional, string) - Optional YouTube channel id for the request.
- handle (optional, string) - Optional YouTube channel handle for the request.
- sortBy (optional, string, enum: latest | popular) - Optional sort order for the returned YouTube videos.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
- includeExtras (optional, boolean) - Optional flag to include richer per-video metadata when available.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/youtube/channels/videos?handle=charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/channels/shorts
List YouTube channel shorts
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/channels/shorts/get.mdx
SDK: client.youtube.getChannelShorts({ handle })
Parameters:
- channelId (optional, string) - Optional YouTube channel id for the request.
- handle (optional, string) - Optional YouTube channel handle for the request.
- sortBy (optional, string, enum: latest | popular) - Optional sort order for the returned YouTube Shorts.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/youtube/channels/shorts?handle=charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/playlists
Get YouTube playlist
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/playlists/get.mdx
SDK: client.youtube.getPlaylist({ playlistId: "PLP32wGpgzmIlInfgKVFfCwVsxgGqZNIiS" })
Parameters:
- playlistId (required, string) - YouTube playlist id, or a YouTube playlist URL (the `list` query value is used when present).
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/youtube/playlists?playlistId=PLP32wGpgzmIlInfgKVFfCwVsxgGqZNIiS" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/community-posts
Get YouTube community post
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/community-posts/get.mdx
SDK: client.youtube.getCommunityPost({ url: "https://www.youtube.com/post/Ugkxvj2KoApYAXoqLWnKVr6zZe5JjeHrQeP8" })
Parameters:
- url (required, string) - Public YouTube community post URL.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/youtube/community-posts?url=https://www.youtube.com/post/Ugkxvj2KoApYAXoqLWnKVr6zZe5JjeHrQeP8" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/search
Search YouTube
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/search/get.mdx
SDK: client.youtube.search({ query: "running" })
Parameters:
- query (required, string) - Search query text for YouTube content.
- uploadDate (optional, string, enum: today | this_week | this_month | this_year) - Optional upload date filter for video results.
- sortBy (optional, string, enum: relevance | popular) - Optional sort order for search results.
- type (optional, string, enum: videos | shorts | channels | playlists) - Optional content type filter for search results.
- duration (optional, string, enum: under_3_min | between_3_and_20_min | over_20_min) - Optional duration filter for video results. Applies to videos, not shorts.
- region (optional, string) - Optional ISO 3166-1 country code for localized search results.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
- includeExtras (optional, boolean) - When true, returns richer per-video metadata when available. May increase response time.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Disambiguation: Use `data.page.hasMore` and `data.page.nextCursor` for pagination rather than inferring completion from bucket sizes alone.
curl "https://api.socialfetch.dev/v1/youtube/search?query=value" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/search/hashtags
Search YouTube by hashtag
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/search/hashtags/get.mdx
SDK: client.youtube.searchHashtag({ hashtag: "funny" })
Parameters:
- hashtag (required, string) - Hashtag to search for. A leading # is optional.
- type (optional, string, enum: all | shorts) - Optional content filter.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Disambiguation: Use `data.page.hasMore` and `data.page.nextCursor` for pagination rather than inferring completion from result count alone.
curl "https://api.socialfetch.dev/v1/youtube/search/hashtags?hashtag=trending" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/shorts/trending
List trending YouTube Shorts
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/shorts/trending/get.mdx
SDK: client.youtube.getTrendingShorts()
Disambiguation: Typically returns about 48 trending Shorts per call. Repeat the same request for another fresh batch (new and overlapping Shorts are both possible). No cursor or page parameters.
curl "https://api.socialfetch.dev/v1/youtube/shorts/trending" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/videos
Get YouTube video
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/videos/get.mdx
SDK: client.youtube.getVideo({ url })
Parameters:
- url (required, string) - Link to the YouTube video. Shorts URLs are also supported.
- language (optional, string) - Optional preferred language for returned text when the source supports localization.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/youtube/videos?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/videos/comments
List YouTube video comments
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/videos/comments/get.mdx
SDK: client.youtube.getVideoComments({ url, order: "top" })
Parameters:
- url (required, string) - Link to the YouTube video whose comments should be listed.
- cursor (optional, string) - Opaque cursor from a previous response to fetch the next page.
- order (optional, string, enum: top | newest) - Comment sort order. `top` returns highest-ranked comments; `newest` returns the most recent comments.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/youtube/videos/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/videos/comments/replies
List YouTube comment replies
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/videos/comments/replies/get.mdx
SDK: client.youtube.getVideoCommentReplies({ cursor: comment.repliesCursor })
Parameters:
- cursor (required, string) - Comment `repliesCursor` from Video Comments endpoint, or `page.nextCursor` to paginate replies.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/youtube/videos/comments/replies?cursor=Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIaVWd6Z2UzNDBkQmdCNzVoV0JtNTRBYUFCQWciAggAKhhVQ3VBWEZrZ3N3MUw3eGFDZm5kNUpKT3cyC2RRdzR3OVdnWGNRQABICoIBAggBQi9jb21tZW50LXJlcGxpZXMtaXRlbS1VZ3pnZTM0MGRCZ0I3NWhXQm01NEFhQUJBZw%3D%3D" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/youtube/videos/transcript
Get YouTube video transcript
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/youtube/videos/transcript/get.mdx
SDK: client.youtube.getVideoTranscript({ url })
Parameters:
- url (required, string) - Link to the YouTube video whose transcript should be returned.
- language (optional, string) - Optional ISO 639-1 language code (two letters) to prefer when multiple transcripts exist.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `lookup_failed`
curl "https://api.socialfetch.dev/v1/youtube/videos/transcript?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: YOUR_API_KEY"