# SocialCrawl API — youtube endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/youtube

## GET /v1/youtube/channel
Get YouTube channel info
Credit cost: 1 (standard)
Parameters:
- channelId (optional, string) — YouTube channel ID. Can pass a channelId, handle or url
- handle (optional, string) — YouTube channel handle without the @ symbol
- url (optional, string) — YouTube channel URL. Can pass a channelId, handle or url
- Constraint: one of channelId, handle, url (at least one required)
curl "https://www.socialcrawl.dev/v1/youtube/channel" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/channel/videos
List YouTube channel videos
Credit cost: 1 (standard)
Parameters:
- channelId (optional, string) — YouTube channel ID
- handle (optional, string) — YouTube channel handle without the @ symbol
- sort (optional, enum: latest | popular) — Sort by latest or popular
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- includeExtras (optional, string) — This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. This will slow down the response slightly.
- Constraint: one of channelId, handle (at least one required)
curl "https://www.socialcrawl.dev/v1/youtube/channel/videos" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/video
Get YouTube video details
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the YouTube video
- language (optional, string) — Preferred response language (mapped to Accept-Language header; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc.
curl "https://www.socialcrawl.dev/v1/youtube/video?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/video/comments
List YouTube video comments
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the YouTube video to fetch comments for
- continuationToken (optional, string) — Continuation token to get more comments. Get 'continuationToken' from previous response.
- order (optional, enum: top | newest) — Order of comments
curl "https://www.socialcrawl.dev/v1/youtube/video/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/video/comment/replies
List YouTube comment replies
Credit cost: 1 (standard)
Parameters:
- continuationToken (required) — Continuation token for the comment replies. Use 'repliesContinuationToken' from the Comments endpoint, or 'continuationToken' from a previous replies response to paginate.
curl "https://www.socialcrawl.dev/v1/youtube/video/comment/replies?continuationToken=Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIa..." \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/search
Search YouTube videos
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase to find YouTube videos
- uploadDate (optional, enum: today | this_week | this_month | this_year) — Upload date
- sortBy (optional, enum: relevance | popular) — Sort by
- filter (optional, enum: shorts) — Filter by these options. Note this doesn't work when you use either 'uploadDate' or 'sortBy'. It basically only works when you have a query.
- region (optional, string) — 2 letter country code of the country to put the proxy in.
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- includeExtras (optional, string) — This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. *This will slow down the response slightly.*
curl "https://www.socialcrawl.dev/v1/youtube/search?query=javascript tutorial" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/channel/shorts
List YouTube channel shorts
Credit cost: 1 (standard)
Parameters:
- handle (optional, string) — YouTube channel handle without the @ symbol
- channelId (optional, string) — Can pass channelId or handle
- sort (optional, enum: newest | popular) — Sort by newest or popular
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- Constraint: one of channelId, handle (at least one required)
curl "https://www.socialcrawl.dev/v1/youtube/channel/shorts" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/community-post
Get YouTube community post
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the YouTube community post
curl "https://www.socialcrawl.dev/v1/youtube/community-post?url=https://www.youtube.com/post/UgkxCWeKpIOHLknREsNOF9M_aqz4fKkCERjP" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/playlist
Get YouTube playlist
Credit cost: 1 (standard)
Parameters:
- playlist_id (required) — YouTube playlist ID
curl "https://www.socialcrawl.dev/v1/youtube/playlist?playlist_id=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/search/hashtag
Search YouTube by hashtag
Credit cost: 1 (standard)
Parameters:
- hashtag (required) — Hashtag to search for without the # symbol
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- type (optional, enum: all | shorts) — Search for all types of content or only shorts
curl "https://www.socialcrawl.dev/v1/youtube/search/hashtag?hashtag=shorts" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/shorts/trending
Get trending YouTube shorts
Credit cost: 5 (advanced)
curl "https://www.socialcrawl.dev/v1/youtube/shorts/trending" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/youtube/video/transcript
Get YouTube video transcript
Credit cost: 10 (premium)
Parameters:
- url (required) — Full URL of the YouTube video
- language (optional, string) — 2 letter language code, ie 'en', 'es', 'fr' etc. If the transcript is not available in the language you specify, the transcript will be null.
curl "https://www.socialcrawl.dev/v1/youtube/video/transcript?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_your_api_key_here"