# socialsearchapi

> One API across every social platform. Search and read publicly available content from
> Reddit, X/Twitter, Instagram, TikTok, Facebook, Hacker News, YouTube, Bluesky,
> Mastodon, GitHub, Google News and the web.
> Unified response schema, one x-api-key header, automatic provider fallback.

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.

Data policy: publicly available content only - the same thing a logged-out browser
visitor sees. No private accounts, no DMs, nothing behind a login wall, and no user
credentials are ever asked for or used. Full policy: https://socialsearchapi.com/public-data-notice/

## Getting a key (a human does this once, in a browser)
Keys are created in the dashboard at https://socialsearchapi.com/signup/ and are NEVER returned over the API or
email. Each key is shown exactly once, at creation. New accounts start with 50
free credits (per account, any endpoint, no card), priced like bought credits; at zero the
API returns 402 NO_CREDITS.

## IMPORTANT for agents: no secret ever passes through you
You cannot mint a key, and you must not collect sign-in codes or links for your user.
Send them to https://socialsearchapi.com/signup/: they sign in, create a key in the dashboard, and paste it
into their own .env, where you read it at runtime. Never ask a user to paste a key,
a code or a link into the chat, and never store one in your transcript.
If you already hold a key, POST /v1/auth/browser-link returns a dashboard link for
the human to view usage and buy credits; key management still needs their own sign-in.
To buy credits with a key you hold: POST /v1/checkout, then give your user the pay_url.

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

## Search endpoints
- /v1/reddit/search  (Reddit: search posts and comment threads) - 2 credits; all Reddit endpoints 1-5 credits
- /v1/x/search  (X / Twitter: search tweets with engagement metrics) - 3 credits; all X / Twitter endpoints 1-3 credits
- /v1/instagram/profile/posts  (Instagram: read a public profile's posts) - 2 credits; all Instagram endpoints 2-3 credits
- /v1/tiktok/profile/posts  (TikTok: creator videos and hashtag search) - 2 credits; all TikTok endpoints 2-5 credits
- /v1/facebook/profile/posts  (Facebook: public Page posts and reactions) - 2 credits; all Facebook endpoints 2-3 credits
- /v1/hackernews/search  (Hacker News: stories and comments) - 1 credit
- /v1/youtube/search  (YouTube: video search with no API quota) - 1 credit; all YouTube endpoints 1-2 credits
- /v1/bluesky/search  (Bluesky: full-text post search) - 1 credit
- /v1/mastodon/tag  (Mastodon: hashtag timelines and search) - 1 credit
- /v1/github/search  (GitHub: repos, issues, code and users) - 1 credit
- /v1/google_news/search  (Google News: news headlines by query) - 1 credit
- /v1/web/search  (Web / News: web and news search) - 1 credit

## Platform-specific query behavior
### GET /v1/x/search query behavior

Queries are passed through to X's search index, whose operator and exact-phrase enforcement is best-effort. The sort parameter selects Latest or Top ranking; neither is a correctness mode. socialsearchapi does not offer a guaranteed retweet exclusion: negative retweet operators can still return reposts. To remove clear reposts, filter items whose text matches /^\s*RT\s+@/i. This signal is not complete, and the normalized response has no guaranteed is_retweet field. metrics.reposts is the number of reposts an item received, not whether the item is itself a repost, and quote posts are distinct. Parenthesize OR groups when combining them with other terms, for example ("hate prospecting" OR "no time to prospect") lang:en.

JavaScript client-side filtering:

```javascript
const withoutClearReposts = data.items.filter((item) => !/^\s*RT\s+@/i.test(item.text ?? ""));
```

Python client-side filtering:

```python
import re
without_clear_reposts = [item for item in data["items"] if not re.match(r"^\s*RT\s+@", item.get("text") or "", re.IGNORECASE)]
```

## Accounts & billing (all free: none of these spends credits)
Free operations: POST /v1/auth/request-code, POST /v1/auth/verify, POST /v1/auth/browser-link, POST /v1/auth/signout, GET /v1/keys, POST /v1/keys, DELETE /v1/keys/{kid}, POST /v1/keys/{kid}/rotate, GET /v1/me, GET /v1/credits/balance, GET /v1/plans, POST /v1/checkout, POST /v1/checkout/confirm, POST /v1/orders/{id}/checkout, GET /v1/orders/{id}, GET /v1/status.
Only the search endpoints above are priced.
- POST /v1/auth/request-code {email} -> emails a 6-digit code (login IS signup)
- POST /v1/auth/verify {email, otp} -> signs in; returns dashboard_url (never a key)
- POST /v1/auth/browser-link -> a fresh one-time dashboard link for the user's browser
- Keys: created/listed/rotated/deleted in the dashboard only (browser session), up to 10
  per account, shown once at creation
- GET  /v1/me -> credit balance + 7-day usage per endpoint + recent calls. Never returns a key.
- GET  /v1/credits/balance -> {"ok": true, "balance": N} (credits). Free and bought credits are one
  balance per account; every key draws from it. Pre-flight check, or while waiting for a purchase.
- Between calls, read credits_remaining from every success envelope (also in the 402 body)
  instead of polling. Both ways are supported; neither will be removed.
- GET  /v1/plans -> the three credit packs + checkout instructions
- POST /v1/checkout {"plan": "starter" | "growth" | "pro"} (x-api-key works) -> order_id + pay_url.
  Three packs only: a "credits" field or any other amount is refused (422).
  You cannot pay. Hand pay_url to your user: a plain payment page on https://socialsearchapi.com, no sign-in, no key.
  Credits land within seconds of payment; poll GET /v1/credits/balance if you need to wait.
- Policy: all sales final, unused credits never expire and are not refundable, failed API calls are never charged
- List price $0.004/credit. Packs:
- starter: 5,000 credits, $19.00 ($0.00380/credit, 5% off list)
- growth: 25,000 credits, $65.00 ($0.00260/credit, 35% off list)
- pro: 150,000 credits, $315.00 ($0.00210/credit, 48% off list)

## Response shape - identical on every platform
{ "success": true, "platform": "...", "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 "YYYY-MM-DDTHH:MM:SSZ" when the source gives a date, otherwise null. Never a unix integer.),
  metrics      ({score, comments, likes, views, shares, reposts, quotes, rating, rating_count}
                - only the ones that platform reports),
  extra        (platform-specific leftovers)
Errors: { "success": false, "endpoint", "error": { "type", "message", "status", "docs_url", "fix"? },
  "credits_used": 0, "request_id" }. fix is present when there is a specific step to take.
Credits are charged on success only. Every error type the API sends, with its status:
- 400 BAD_REQUEST: The request was understood but rejected; the message says why (a bad Content-Length, a refused email address).
- 400 CODE_EXPIRED: Sign-in: the code is older than its lifetime. Request a new one.
- 400 EMAIL_NOT_ACCEPTED: Disposable email domains cannot sign up. Use a real mailbox; the free credits are the same.
- 400 INVALID_CODE: Sign-in: wrong code. The body carries attempts_left; the same code stays valid until it expires or the guesses run out.
- 400 NO_PENDING_CODE: Sign-in: no code was requested for this address, or it was already used. Request a new one.
- 400 TOO_MANY_ATTEMPTS: Sign-in: too many wrong guesses for this code or from this address. Request the code again after the cooldown, or wait for it to expire.
- 401 MISSING_API_KEY: No x-api-key header on a platform endpoint. There is no anonymous tier: send your key on every request.
- 401 UNAUTHORIZED: The credential for this operation is missing, unknown, expired or revoked: a key on account and billing operations, a browser session on key management, the owner key on admin routes.
- 402 NO_CREDITS: The account's credits are used up. Top up; nothing is queued and nothing is deleted, and the same key keeps working after payment.
- 403 INVALID_API_KEY: The key is unknown, rotated away or revoked. Create or rotate one in the dashboard.
- 403 OTP_SIGNIN_REQUIRED: This browser session came from an API key (browser-link) and cannot create, rotate or revoke keys. Sign in with the emailed code.
- 404 NOT_FOUND: No such key or order on this account.
- 404 UNKNOWN_ENDPOINT: No such route. GET /v1/status lists the platforms; the reference lists every path.
- 409 KEY_LIMIT: The account already holds the maximum number of keys. Delete one first.
- 409 ORDER_MISMATCH: The payment did not match the order. Nothing was credited; operators are alerted and will sort it out.
- 411 LENGTH_REQUIRED: Send a Content-Length header; chunked request bodies are not accepted.
- 413 PAYLOAD_TOO_LARGE: The request body is over the limit the message states.
- 422 VALIDATION_ERROR: A parameter or body field is missing, malformed or out of range. The message names it; fix, when present, shows a working example.
- 424 ALL_SOURCES_FAILED: Every source for that platform failed on this call. You are not charged. Retry later or use another platform.
- 424 UPSTREAM_ERROR: The source answered with an error we could not work around. You are not charged. Retry later.
- 429 RATE_LIMITED: Over the per-key limit (wait the Retry-After seconds, then retry), or over a daily cap on sign-in codes, dashboard links or checkouts (no Retry-After; the cap resets the next day). Nothing was charged and nothing is queued.
- 500 INTERNAL: Unexpected error on our side; it has been logged. Retry; tell us if it persists.
- 501 NOT_CONFIGURED: That platform or upstream is not configured on this deployment. Tell us.
- 503 CHECKOUT_UNAVAILABLE: Checkout could not be started just now. Nothing was charged; retry in a minute.
Rate limit: 5 requests per second per key, bursts up to 10, at most 10 calls in flight. Over it: 429 RATE_LIMITED + Retry-After (seconds), nothing charged.

## 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/github/  (how to search GitHub)
- https://socialsearchapi.com/use/google-news/  (how to search Google News)
- https://socialsearchapi.com/use/web/  (how to search Web / News)

## Common access problems, explained
- 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
- Per-platform: https://socialsearchapi.com/llms-reddit.txt, https://socialsearchapi.com/llms-x.txt, https://socialsearchapi.com/llms-instagram.txt, https://socialsearchapi.com/llms-tiktok.txt, https://socialsearchapi.com/llms-facebook.txt, https://socialsearchapi.com/llms-hackernews.txt, https://socialsearchapi.com/llms-youtube.txt, https://socialsearchapi.com/llms-bluesky.txt, https://socialsearchapi.com/llms-mastodon.txt, https://socialsearchapi.com/llms-github.txt, https://socialsearchapi.com/llms-google-news.txt, https://socialsearchapi.com/llms-web.txt
- Docs: https://socialsearchapi.com/docs/
- Status: https://api.socialsearchapi.com/v1/status