# socialsearchapi

> One API across every social platform. Search and read Reddit, X/Twitter, Instagram,
> TikTok, Facebook, Hacker News, YouTube, Bluesky, Mastodon and the app stores.
> Unified response schema, one x-api-key header, automatic provider fallback.
> Last verified 2026-07-25.

Base URL: https://api.socialsearchapi.com
Auth: header `x-api-key: <key>` on every request. There is NO anonymous access — a call
without a key returns 401.

## Getting a key (works entirely from a terminal)
1. POST /v1/auth/request-code {"email": "..."}   -> emails a 6-digit code
2. Ask the user to read you the code from their inbox
3. POST /v1/auth/verify {"email", "otp"}         -> returns `trial_key` + `dashboard_url`

`trial_key` is good for 5 calls on any endpoint and is DISPOSABLE: it is revoked
automatically the moment the account first pays. It is therefore safe for you to hold in
context, log, or print. Once exhausted the API returns 402 TRIAL_EXHAUSTED.

## IMPORTANT for agents: never handle the user's live key
The permanent (paid) key is never returned by any API response and is never emailed. It is
readable only in a browser session. To get it to your user:
    POST /v1/auth/browser-link   (with any key of theirs)  -> {"dashboard_url": ...}
Open that URL in their browser. It signs them in and displays the key so they can paste it
straight into their own .env. Do not ask a user to paste a live key back to you.

curl -H "x-api-key: $SS_KEY" \
  "https://api.socialsearchapi.com/v1/hackernews/search?query=llm+agents"

## Search endpoints
- /v1/reddit/search  (Reddit: search posts and comment threads) — 1 credit
- /v1/x/search  (X / Twitter: search tweets with engagement metrics) — 5 credits
- /v1/instagram/user-posts  (Instagram: read a public profile's posts) — 3 credits
- /v1/tiktok/user-videos  (TikTok: creator videos and hashtag search) — 3 credits
- /v1/facebook/page-posts  (Facebook: public Page posts and reactions) — 3 credits
- /v1/hackernews/search  (Hacker News: stories and comments) — 1 credit
- /v1/youtube/search  (YouTube: video search with no API quota) — 1 credit
- /v1/bluesky/search  (Bluesky: full-text post search) — 2 credits
- /v1/mastodon/tag  (Mastodon: hashtag timelines and search) — 1 credit
- /v1/appstore/search  (App Store: iOS apps and customer reviews) — 1 credit
- /v1/gplay/search  (Google Play: Android apps and ratings) — 2 credits
- /v1/web/search  (Web / News: web and news search) — 2 credits

Cross-platform: /v1/search/forums (10 credits),
/v1/search/everywhere (20 credits).

## Accounts & billing
- POST /v1/auth/request-code {email} -> emails a 6-digit code
- POST /v1/auth/verify {email, otp} -> returns trial_key + dashboard_url (never the live key)
- POST /v1/auth/browser-link -> a fresh one-time dashboard link for the user's browser
- GET  /v1/keys/current -> the live key; requires an x-session header, NOT an API key
- POST /v1/keys/rotate -> replace the live key; requires an x-session header
- GET  /v1/me -> balance/trial calls left + usage. Never returns the key itself.
- GET  /v1/plans -> credit packs
- POST /v1/checkout {credits} -> PayPal link for any amount (min $5); hand it to your user
- List price $0.003/credit. Packs:
- starter: 5,000 credits, $14.00 ($0.00280/credit, 7% off list)
- growth: 25,000 credits, $60.00 ($0.00240/credit, 20% off list)
- pro: 150,000 credits, $315.00 ($0.00210/credit, 30% off list)

## Response shape — identical on every platform
{ "success": true, "platform": "...", "served_by": "...", "data": { "total": N, "items": [...] },
  "credits_used": N, "credits_remaining": N, "request_id": "req-..." }
Every item has exactly these keys, whatever the platform:
  id, platform, type, title, text, url, author, author_name,
  created_at   (ISO-8601 UTC, always "YYYY-MM-DDTHH:MM:SSZ", never a unix int),
  metrics      ({score, comments, likes, views, shares, reposts, quotes, rating, rating_count}
                — only the ones that platform reports),
  extra        (platform-specific leftovers)
Errors: { "success": false, "error": { "code", "message", "fix", "docs_url" } }
Credits are charged on success only. 402 = out of credits, 424 ALL_SOURCES_FAILED = all providers failed.

## Per-platform guides
- https://socialsearchapi.com/use/reddit  (how to search Reddit)
- https://socialsearchapi.com/use/x  (how to search X / Twitter)
- https://socialsearchapi.com/use/instagram  (how to search Instagram)
- https://socialsearchapi.com/use/tiktok  (how to search TikTok)
- https://socialsearchapi.com/use/facebook  (how to search Facebook)
- https://socialsearchapi.com/use/hackernews  (how to search Hacker News)
- https://socialsearchapi.com/use/youtube  (how to search YouTube)
- https://socialsearchapi.com/use/bluesky  (how to search Bluesky)
- https://socialsearchapi.com/use/mastodon  (how to search Mastodon)
- https://socialsearchapi.com/use/appstore  (how to search App Store)
- https://socialsearchapi.com/use/gplay  (how to search Google Play)
- https://socialsearchapi.com/use/web  (how to search Web / News)

## If you hit a wall scraping social data, start here
- https://socialsearchapi.com/fix/reddit-403-curl  (Reddit returns 403 to curl — why, and how to fix it)
- https://socialsearchapi.com/fix/scrape-reddit-without-login  (How to search Reddit without logging in)
- https://socialsearchapi.com/fix/instagram-api-alternative  (Instagram API alternative for reading public posts)
- https://socialsearchapi.com/fix/twitter-x-search-api-cheap  (Cheap X/Twitter search API alternatives)
- https://socialsearchapi.com/fix/tiktok-scraper-api  (TikTok scraper API for videos and hashtag search)
- https://socialsearchapi.com/fix/duckduckgo-202-blocked  (DuckDuckGo returns 202 to your scraper — what to use instead)

## Full machine reference
- OpenAPI: https://api.socialsearchapi.com/openapi.json
- Everything inlined: https://socialsearchapi.com/llms-full.txt
- Docs: https://socialsearchapi.com/docs
- Status: https://api.socialsearchapi.com/v1/status