# 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
- 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
- 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: 1 (standard)
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/ad
Get Reddit ad details
Credit cost: 5 (advanced)
Parameters:
- id (required) — Reddit ad ID
curl "https://www.socialcrawl.dev/v1/reddit/ad?id=t3_abc123" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/reddit/ads/search
Search Reddit ads
Credit cost: 5 (advanced)
Parameters:
- query (required) — Search query
- industries (optional, enum: RETAIL_AND_ECOMMERCE | TECH_B2B | TECH_B2C | EDUCATION | ENTERTAINMENT | GAMING | FINANCIAL_SERVICES | HEALTH_AND_BEAUTY | CONSUMER_PACKAGED_GOODS | EMPLOYMENT | AUTO | TRAVEL | REAL_ESTATE | GAMBLING_AND_FANTASY_SPORTS | POLITICS_AND_GOVERNMENT | OTHER) — Industries to filter by
- budgets (optional, enum: LOW | MEDIUM | HIGH) — Budgets to filter by
- formats (optional, enum: IMAGE | VIDEO | CAROUSEL | FREE_FORM) — Formats to filter by
- placements (optional, enum: FEED | COMMENTS_PAGE) — Placements to filter by
- objectives (optional, enum: IMPRESSIONS | CLICKS | CONVERSIONS | VIDEO_VIEWABLE_IMPRESSIONS | APP_INSTALLS) — Objectives to filter by
curl "https://www.socialcrawl.dev/v1/reddit/ads/search?query=gaming" \
  -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"