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

## GET /v1/reddit/subreddit
List Reddit subreddit posts
Credit cost: 1 (standard)
Parameters:
- subreddit (required) — Subreddit name without the r/ prefix
- timeframe (optional, enum: all | day | week | month | year) — Timeframe to get posts from. Applied with sort=top (auto-selected when you omit sort).
- sort (optional, enum: best | hot | new | top | rising) — Sort order
- after (optional, string) — After to get more posts. Get 'after' from previous response.
- trim (optional, boolean) — Set to true for a trimmed down version of the response
curl "https://www.socialcrawl.dev/v1/reddit/subreddit?subreddit=technology" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/reddit/subreddit/details
Get Reddit subreddit details
Credit cost: 1 (standard)
Parameters:
- subreddit (optional, string) — Subreddit name without the r/ prefix. Case-sensitive — use the subreddit's canonical casing (e.g. `AskReddit`).
- url (optional, string) — Subreddit URL
- Constraint: one of subreddit, url (at least one required)
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/details" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/reddit/search
Search Reddit posts
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase to find Reddit posts
- sort (optional, enum: relevance | new | top | comment_count) — Sort by
- timeframe (optional, enum: all | day | week | month | year) — Timeframe
- after (optional, string) — Used to paginate to next page
- trim (optional, boolean) — Set to true for a trimmed down version of the response
curl "https://www.socialcrawl.dev/v1/reddit/search?query=best programming languages 2024" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/reddit/post/comments
List Reddit post comments
Credit cost: 5 (advanced)
Parameters:
- url (required) — Full URL of the Reddit post to fetch comments for
- cursor (optional, string) — Cursor to get more comments, or replies.
- trim (optional, boolean) — Set to true for a trimmed down version of the response
curl "https://www.socialcrawl.dev/v1/reddit/post/comments?url=https://www.reddit.com/r/technology/comments/abc123/example_post/" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/reddit/subreddit/search
Search within a subreddit
Credit cost: 1 (standard)
Parameters:
- subreddit (required) — Subreddit name (e.g. 'Fitness', not 'r/Fitness' or a full URL)
- query (optional, string) — Search query to find matching content
- sort (optional, enum: relevance | hot | top | new | comments) — Sort order. For posts/media: relevance, hot, top, new, comments. For comments: relevance, top, new
- timeframe (optional, enum: all | year | month | week | day | hour) — Timeframe to filter results
- cursor (optional, string) — Cursor to get more results. Get 'cursor' from previous response.
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/search?subreddit=technology" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/reddit/post/transcript
Get a Reddit video post transcript
Credit cost: 10 (premium)
Parameters:
- url (required) — Reddit post URL or direct v.redd.it video URL.
- language (optional, string) — 2-letter language code. Defaults to `en`.
curl "https://www.socialcrawl.dev/v1/reddit/post/transcript?url=https://www.reddit.com/r/youseeingthisshit/comments/1oiu9xm/football_nostalgiasaints_punter_head_coach_cant/" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/reddit/omni-search
Reddit VoC sweep: one keyword → threads across all of Reddit with subreddit attribution and top comments inline.
Credit cost: 1 (standard)
Parameters:
- query (required) — Keyword or phrase to sweep across Reddit.
- threads (optional, integer) — How many top threads to expand comments for (1–8, default 8).
- sort (optional, enum: relevance | new | top | comment_count) — Search sort order (relevance | new | top | comment_count).
- timeframe (optional, enum: all | day | week | month | year) — Time window for the search (all | day | week | month | year).
- subreddit (optional, string) — Scope the sweep to one subreddit (bare name, no r/ prefix).
- cursor (optional, string) — Opaque cursor from a prior response's next_cursor to page deeper.
- include (optional, string) — CSV subset of subreddits,comments (default both).
curl "https://www.socialcrawl.dev/v1/reddit/omni-search?query=best mechanical keyboard" \
  -H "x-api-key: sc_your_api_key_here"