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

## GET /v1/search/everywhere
Universal social search across 14 platforms
Credit cost: 20 (override; tier standard)
Parameters:
- query (required) — Search query (1–512 chars)
- lookback_days (optional, integer) — Days to look back (1–365+, default 30); mutually exclusive with from_date/to_date.
- from_date (optional, string) — ISO YYYY-MM-DD lower bound; mutually exclusive with lookback_days.
- to_date (optional, string) — ISO YYYY-MM-DD upper bound; defaults to today when from_date is set alone.
- sources (optional, string) — Optional CSV allowlist of sources (mutually exclusive with exclude). Valid names: reddit, twitter-ai-search, youtube, tiktok, instagram, hackernews, polymarket, github, threads, pinterest, perplexity, tavily, linkedin, rumble, tiktok-hashtag, instagram-hashtag, youtube-hashtag. Platform shorthands expand to their full group: twitter/x → twitter-ai-search; youtube, instagram, tiktok also include their -hashtag lane. Unknown names return a 400.
- exclude (optional, string) — Optional CSV blocklist of sources (mutually exclusive with sources). Same valid names and platform shorthands as sources — excluding youtube/instagram/tiktok also excludes the platform's -hashtag lane. Unknown names return a 400.
curl "https://www.socialcrawl.dev/v1/search/everywhere?query=kanye west" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/search/forums
Fused forum search across Reddit, Hacker News, and Naver 지식iN/카페 — with top comments inline on hero threads by default.
Credit cost: 10 (override; tier standard)
Parameters:
- query (required) — Search query (2–256 chars), forwarded to every forum search.
- sources (optional, string) — Optional CSV allowlist of forum sources (reddit, hackernews, naver_kin, naver_cafe). Mutually exclusive with exclude.
- exclude (optional, string) — Optional CSV blocklist of forum sources. Mutually exclusive with sources.
- comments (optional, string) — Comment enrichment toggle (on|off, default on). 'off' returns thread-only.
- timeframe (optional, string) — Recency window passed to Reddit; HN filtered client-side (all|day|week|month|year, default all).
- lookback_days (optional, integer) — Alt recency window in days (1–365); HN filtered client-side.
curl "https://www.socialcrawl.dev/v1/search/forums?query=airpods pro 3 battery" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/search/creators
Fused creator discovery across TikTok, Threads, and Instagram, ranked by relevance, followers, and verification.
Credit cost: 10 (override; tier standard)
Parameters:
- query (required) — Niche or topic (2-256 chars), forwarded to every profile search.
- sources (optional, string) — Optional CSV allowlist of creator sources (tiktok, threads, instagram). Mutually exclusive with exclude.
- exclude (optional, string) — Optional CSV blocklist of creator sources. Mutually exclusive with sources.
- min_followers (optional, integer) — Drop fused creators whose follower count is below this integer floor.
- verified_only (optional, boolean) — When true, keep only verified creators after fusion.
- sort (optional, enum: relevance | followers | verification) — Which axis dominates rank: relevance (default), followers, or verification.
curl "https://www.socialcrawl.dev/v1/search/creators?query=skincare routine" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/search/news
Planned multi-country news search: one query, localized and fanned out across Google News editions in a single call.
Credit cost: 2-14 (metered) — 2 credits + 1 credit per country/angle leg that returns at least one article. The upfront hold is 2 + min(5 x countries, max_legs, 12) credits (maximum 14) and settles down to the actual charge; empty or failed legs bill 0.
Parameters:
- query (required) — News topic or question (1-500 chars). Boolean AND/OR/NOT and quoted phrases are supported; Google advanced operators (site:, intitle:, before:) are rejected.
- countries (optional, string) — CSV of ISO 3166-1 alpha-2 country codes to search (1-12 of the 50 supported editions, default US). Each country searches its Google News edition in its default language; duplicates collapse.
- time_range (optional, enum: day | week | month | year) — Recency window (day | week | month | year, default day). Ignored when from/to is present.
- from (optional, string) — Lower publish-date bound, YYYY-MM-DD or Unix seconds. Pins every leg to the primary news source.
- to (optional, string) — Upper publish-date bound, YYYY-MM-DD or Unix seconds. Pins every leg to the primary news source.
- publisher (optional, string) — Bare publisher domain filter (e.g. bbc.com; no scheme or path). Pins every leg to the primary news source.
- depth (optional, integer) — Articles requested per leg (10-100 in steps of 10, default 10).
- max_legs (optional, integer) — Hard cap on billable legs (1-12, default 12). The upfront hold shrinks with it.
curl "https://www.socialcrawl.dev/v1/search/news?query=samsung galaxy launch" \
  -H "x-api-key: sc_your_api_key_here"