# Universal Search Everywhere API (https://www.socialcrawl.dev/platforms/search/everywhere)

> One query, searched on every platform at once, returns one ranked list with clusters and top comments. It searches up to 20 sources across 15 platforms: Reddit (`reddit`), X posts (`twitter`), a written summary of X posts (`twitter-ai-search`), YouTube (`youtube`), TikTok (`tiktok`), Instagram (`instagram`), Hacker News (`hackernews`), Polymarket (`polymarket`), GitHub (`github`), Threads (`threads`), Pinterest (`pinterest`), a cited web answer (`perplexity`), web search results (`web`), LinkedIn (`linkedin`), Rumble (`rumble`), Naver (`naver`) and Facebook (`facebook`), plus TikTok hashtags (`tiktok-hashtag`), Instagram hashtags (`instagram-hashtag`) and YouTube hashtags (`youtube-hashtag`) in hashtag mode. `naver` (Naver blog, cafe and KnowledgeiN) joins when the query contains Hangul, and on any query when you name it in `sources`; Naver rows carry the corpus in `metadata.corpus`. `facebook` runs only when you ask for it: `include=facebook` adds it to the default sources, and `sources=facebook` runs only the sources you name; it returns about 5 public posts, newest first inside your date window. The hashtag lanes run only in hashtag mode: an explicit `#tag`, a single word, or a topic term the planner names. A source you name in `sources` is always searched. What ranks and what filters: `lookback_days` is a ranking signal that sets the freshness curve, so an older row can still rank when nothing recent matches; `since`, `until`, `from_date` and `to_date` are hard bounds that drop rows outside the window (rows with no date are kept and counted in `data.since`); `relevance=filter` drops the rows judged off topic; `limit` (1 to 40) trims the answer. Every result carries `computed.relevance` and `computed.stance`, and `data.judgments` says whether each judgment ran. Top comments ride the results on the six lanes that have them (Reddit, Hacker News, YouTube, TikTok, Instagram and GitHub) at `items[i].source_items[0].metadata.top_comments[]`: up to 15 on each of the top 10 results and 5 after, each `{ score, excerpt, truncated, author, url, date }`. X posts (`twitter`, also `x`) are ranked rows. The X summary (`twitter-ai-search`, which takes 15 to 45 seconds) runs only with `include=synthesis` and arrives in `data.synthesis.x` beside the cited web answer (`data.synthesis.web`), never as ranked rows. On the JSON path the X summary is included only when it is ready with the rest of the answer, and otherwise `sources_failed` says so; the stream waits for it. Every source is a call to its own public endpoint, with that endpoint's fallbacks, inside the flat price: a source whose endpoint keeps failing is skipped (`sources_failed` says `skipped: breaker_open`), and `data.platforms` reports each platform's status, rows, latency and outcome code. Each source has 12 seconds (25 seconds when you search one platform, 20 seconds for `facebook`, 6 seconds for `twitter` beside other sources), and a full search usually takes 20 to 30 seconds: allow a 120-second client timeout. Answers are cached for 120 seconds, and a cache hit is free. Each row's `date_confidence` and `date_source` say how far to trust `published_at`. Streams over SSE with `Accept: text/event-stream` (the terminal `done` chunk carries the page blocks of the JSON answer except `platforms` and `synthesis`; on the stream the web answer and the X summary arrive as `items` chunks), or answers JSON with `Accept: application/json`. Flat 20 credits per call: an answer with no row anywhere costs 0 credits, and when fewer than half the planned sources answer, half is refunded. A parameter this endpoint does not take is ignored with a `data._warnings` line, never refused.

TL;DR: `GET /v1/search/everywhere` costs 20 credits per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search query (1-512 chars) |
| `lookback_days` | no | Recency window in days (minimum 1, default 30). This is a ranking signal, not a hard filter: it sets the freshness curve, so a much older item can still rank when nothing recent matches, and it sets the date window sent to `facebook`. When `from_date` is sent too, `from_date` applies. On the stream, windows over 90 days add a `warning` chunk. For hard bounds use `since`, `until`, `from_date` and `to_date`. Check each row's `date_confidence` and `date_source` before filtering on its date: `low` means the date is an estimate (a rounded YouTube label, a KnowledgeiN estimate). |
| `from_date` | no | Lower date bound, YYYY-MM-DD (from the start of that UTC day) or an ISO 8601 timestamp; when `lookback_days` is sent too, `from_date` applies. A hard bound on `items`: rows dated before it are dropped, rows with no date are kept, and `data.since` reports `{ since, until, dropped, kept_undated }`. Sent with `since`, the later of the two applies and `data._warnings` says so. An invalid date is a free 400. |
| `to_date` | no | Upper date bound, YYYY-MM-DD (to the end of that UTC day, inclusive) or an ISO 8601 timestamp; defaults to today when from_date is set alone. A hard bound on `items`: rows dated after it are dropped, rows with no date are kept. Sent with `until`, the earlier of the two applies and `data._warnings` says so. An invalid date is a free 400. |
| `since` | no | Only rows published at or after this time (ISO 8601 timestamp or date), for polling: pass the previous run's time. A hard filter on `items`, unlike lookback_days; rows with no date are kept and `data.since` reports `{ since, until, dropped, kept_undated }`. Billed as usual. |
| `until` | no | Only rows published at or before this time: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. A hard filter on `items`, like since; rows with no date are kept and counted in `data.since`. Billed as usual. An invalid date is a free 400. |
| `period` | no | A window that holds, by name: `Nd` (1 to 3650 days, ending now), `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`, `last_quarter`, `this_year` or `ytd`, with calendar periods read in `tz`. Each platform is sent its own date filter, and every row is checked against the window again, so rows outside it are dropped whatever the platform did; `data.request.window` echoes the resolved window and `data.platforms.<p>.window` counts the rows dropped. `since`, `until`, `from_date`, `to_date` and `lookback_days` win over `period` when sent with it, and `data._warnings` says so. Billed as usual. |
| `tz` | no | IANA time zone name (default UTC, for example Asia/Seoul) that `period` and bare `since`, `until`, `from_date` and `to_date` dates are read in. An unknown zone is a free 400. |
| `undated` | no | What a row with no date does inside a window: `keep` (default) keeps it and counts it in `data.request.window.undated_kept`, `drop` removes it and counts it in `undated_dropped`. Applies only when a window is set. (keep \| drop) |
| `limit` | no | How many ranked results `items` returns, 1 to 40 (default 40). Above 40 is clamped to 40 with a `data._warnings` line. It trims the answer only: the search, its price and its cache entry are the same whatever the limit, so `limit=10` then `limit=20` on the same query is one billed search. |
| `sources` | no | Optional CSV allowlist of sources (mutually exclusive with exclude). Valid names: reddit, twitter, twitter-ai-search, youtube, tiktok, instagram, hackernews, polymarket, github, threads, pinterest, perplexity, web, linkedin, rumble, tiktok-hashtag, instagram-hashtag, youtube-hashtag, naver, facebook. `naver` (Naver blog, cafe and KnowledgeiN) is in the default set only when the query contains Hangul. `facebook` (public post search) runs only when you name it here. `x` is another name for `twitter` (X posts) and `tavily` for `web`; `twitter-ai-search` here means `twitter` plus include=synthesis. Platform shorthands expand to their full group: youtube, instagram, tiktok also include their -hashtag lane. Unknown names return a 400. |
| `platforms` | no | Another name for sources, with the same values. When both are sent and differ, sources applies and `data._warnings` says so. |
| `exclude` | no | 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. |
| `include_transcripts` | no | Fetch spoken-word transcripts for the top 3 video results (default false), so a video whose title never mentions your query but whose narration does can still be found and quoted. Applies to the YouTube, Rumble, TikTok and Instagram lanes; YouTube and Rumble transcripts carry timestamped segments, TikTok and Instagram are plain text. Transcripts land on `data.items[i].source_items[0].metadata.transcript` and stream as `transcript_enriched` chunks. Included in the flat 20 credits. |
| `relevance` | no | Optional. filter drops the ranked results our relevance judgment already scored as off-topic for your query (unrelated, or clearly about a different thing that shares its words) and lists their ids in data.relevance.dropped_ids, with counts. A result that could not be judged is never dropped; when none could be judged nothing is dropped and data._warnings says relevance_unavailable. items_by_source is not filtered. Omit it to keep every ranked result, ordered as before; each result still carries computed.relevance by default (see judgments). Included in the flat 20 credits. (filter) |
| `include` | no | Optional CSV of extra blocks and opt-in sources. synthesis adds the X summary (twitter-ai-search) and returns it in data.synthesis.x with its citations. facebook adds Facebook public post search to the default sources (it is not in the default fan-out, and `sources=` would replace the defaults instead). stance is now on by default and accepted for compatibility: data.items[i].computed.stance ({ label: positive, negative, neutral, no_opinion or null when unsure, probabilities, confidence }) says what each post, with any replies shown, says about your query, and data.stance_split counts it per platform and overall with the ids behind every count. Posts judged under the confidence floor count as uncertain, never as a stance. If the judgment is unavailable the search still returns, stance is null and data._warnings says stance_unavailable (or stance_skipped when judging was skipped). Included in the flat 20 credits. |
| `judgments` | no | Optional. on (default) or off. On, every result also carries data.items[i].computed.stance (see include) and data.items[i].computed.relevance ({ score 0 to 1, on_topic, entity }), with data.relevance counting the off-topic results and listing their ids. Nothing is dropped or reordered and the price does not change. off returns the response without these blocks. (on \| off) |
| `switch_from` | no | Optional brand. data.switch_receipts lists results where the author says they personally left that brand, with the verbatim text, the reason, where they went, and the link. There is no percentage. Rows that are not a switch stay in items. Included in the flat 20 credits. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/search/everywhere" \
  --data-urlencode "query=kanye west" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I use the social media search API?

Send GET /v1/search/everywhere?query=your+topic with your API key. SocialCrawl fans the query out across Reddit, X, YouTube, TikTok, Instagram, Hacker News, Polymarket, GitHub, Threads, Pinterest, Perplexity, and Tavily in parallel and returns one ranked, clustered JSON result set.

### What parameters does /v1/search/everywhere accept?

query is required (1–512 characters). Optional: lookback_days (default 30), from_date and to_date for an explicit ISO date range, sources for a CSV allowlist of platforms, and exclude for a CSV blocklist. lookback_days and the date range are mutually exclusive, as are sources and exclude.

### What does each search result include?

Each ranked item carries the post, its platform, engagement and freshness signals, and real top comments, up to 5 per result, sorted by score, with 300-character excerpts. Comments come from the platforms themselves: Reddit upvoted replies, YouTube and TikTok top-liked comments, GitHub issue discussion.

### Can I restrict the search to specific platforms?

Yes. Pass sources as a CSV allowlist (for example sources=reddit,youtube,github) to fan out only to those platforms, or exclude as a blocklist to skip platforms. The price stays a flat 20 credits either way.

### How much does one search everywhere call cost?

A flat 20 credits per call, regardless of how many sources fire or how much comment enrichment lands. If the pipeline produces zero ranked items, the credits refund automatically, sync and streaming both.

### Does the endpoint support streaming responses?

Yes. With Accept: text/event-stream you get typed SSE chunks, including comments_enriched chunks as each candidate's comments land, before the terminal done event. With Accept: application/json (the default) you get one synchronous envelope.

See the full Universal Search API: https://www.socialcrawl.dev/platforms/search

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to use the SocialCrawl search everywhere endpoint
- What does GET /v1/search/everywhere return?