# Universal Search (/docs/search) One query, many sources. Fanned out in parallel, ranked, deduped, and enriched with real comments One query fans out across many sources in parallel, and you get back a single ranked, deduplicated result set. Four endpoints share the idea and differ in what they sweep: everything social, forums only, creators only, or news. A fifth, `search/multi`, skips the planning and ranking and returns each platform's own search rows for one query at each platform's own price. Base URL: `/v1/search/...` ## Quickstart ### 1. Make the call ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/search/everywhere?query=best+noise+cancelling+headphones" \ -H "x-api-key: YOUR_API_KEY" ``` ### 2. Stream it if the query is broad Send `Accept: text/event-stream` and each candidate arrives as it settles, including a `comments_enriched` chunk per result, instead of waiting for the whole fan-out. Send `Accept: application/json` for one envelope. ### 3. Read computed fields When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (`computed.labels`, `computed.relevance`) by default at no extra credits; see [Labels](/docs/labels.md). ## Pick a lane | Endpoint | Credits | What it returns | Key parameters | | --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `GET /v1/search/everywhere` | 20 flat | The full social sweep: ranked, clustered candidates enriched with the top comments from each source, each with a stance and a relevance score | `query`, `lookback_days`, `from_date`, `to_date`, `sources`, `exclude`, `relevance`, `judgments` | | `GET /v1/search/forums` | 10 | Discussion threads only, from Reddit, Hacker News and Naver 지식iN and 카페, with top comments inline on hero threads by default, each with a relevance score | `query`, `sources`, `exclude`, `comments`, `timeframe`, `lookback_days`, `relevance`, `judgments` | | `GET /v1/search/creators` | 10, 12 with `brief`; `country` adds up to 12 | Fused creator discovery across TikTok, Threads and Instagram, ranked by relevance, followers and verification, each with an account kind; with `country`, the creators who post about the query in one market | `query`, `sources`, `exclude`, `min_followers`, `verified_only`, `sort`, `brief`, `relevance`, `judgments`, `country` | | `GET /v1/search/news` | 2-14 metered | One query planned into angles, localized per country edition, and merged into one deduplicated article list grouped into same-event stories | `query`, `countries`, `time_range`, `from`, `to`, `publisher`, `depth`, `max_legs`, `group`, `judgments` | | `GET /v1/search/multi` | 1-14 metered | Each platform's own search rows for one query from TikTok, Instagram, YouTube, Reddit, Threads, X, Facebook, LinkedIn and Telegram, deduped by URL, with no planning or reranking | `query`, `platforms`, `since`, `.`, `relevance`, `label` | Every lane adds its judgments by default at no extra credit, and `judgments=off` returns the response without them. [Labels](/docs/labels.md) documents the field shapes and how each was measured. ## Universal social search `/v1/search/everywhere` fans out across 15 platforms in parallel, and up to 20 sources once TikTok, Instagram and YouTube add their hashtag-search siblings in hashtag mode. It ranks the merged set with an LLM judge, clusters near-duplicates, and enriches each result with the top comments from its source: Reddit upvoted replies, Hacker News thread comments, YouTube, TikTok and Instagram top-liked, GitHub issue discussion. Flat 20 credits per call. See the [full endpoint reference](/docs/search/everywhere.md). ## Forums and creators `/v1/search/forums` narrows the same idea to discussion sources when you want opinion threads rather than the whole web. `comments` (`on` by default) controls whether hero threads carry their top comments inline, and `timeframe` (`all`, `day`, `week`, `month`, `year`) or `lookback_days` sets recency. To find creators to work with, measured from their recent posts, judged against your brief and ranked in a market and size band, use [creator search](/docs/prism/creators.md) (`/v1/prism/creators`) instead. `/v1/search/creators` sweeps profile search rather than post search, fuses the results, and ranks them. `sort` picks which axis dominates: `relevance` (the default), `followers`, or `verification`. `min_followers` drops everything below a floor, and `verified_only` keeps only verified accounts after fusion. Both take a `query` of 2 to 256 characters, and both accept `sources` or `exclude` as a CSV, never both. ### Judged relevance on forum threads Every thread on `/v1/search/forums` carries `computed.relevance` by default: `{ p, sense, on_topic }`, where `p` is the probability that the thread is about what your query means and `sense` says whether the key word refers to that thing or to a different one with the same name. It rides the call that already judges each thread's stance, so it adds no wait and no credit. The fused order is kept and nothing is dropped; `data.relevance` counts the result with `mode: "default"`. ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/search/forums?query=jaguar+car&relevance=filter" \ -H "x-api-key: YOUR_API_KEY" ``` `relevance=score` reorders threads by relevance blended with their fused rank, and `relevance=filter` also drops the off-topic ones, lists them in `data.relevance.dropped_ids`, and recounts `stance_split`, `question_share` and `top_communities` over the threads it kept. `relevance_threshold` (0 to 1, default 0.5) sets the bar. Both stay inside the flat 10 credits, and a thread too short to judge is never dropped. ### Account kind and `brief=` on creators The first 40 creators on `/v1/search/creators` carry an `account` block by default, judged from their name, handle and bio: `{ account_kind, account_kind_confidence, named_person }`. `account_kind` is `individual_creator`, `brand_or_business`, `media_or_publisher`, `fan_or_repost_page`, `cannot_tell`, or `null` when unsure, and `individual_creator` is published only when the profile shows one particular person. The order does not change, it is free, and `data.account_kinds` reports how many were judged. To rank by fit, describe what you want in your own words: ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/search/creators?query=latte+art&brief=Baristas+and+home+coffee+creators+who+post+latte+art+videos" \ -H "x-api-key: YOUR_API_KEY" ``` With `brief=` (3 to 300 characters), each of the first 40 creators gains `brief_match`: `{ fits_brief, account_kind, account_kind_confidence, brief_score }`, and with the default `sort=relevance` the list is re-ranked so individual creators who post about your brief lead, with brands, shops and repost pages below them. Other sorts keep their order and only gain the labels. `relevance=filter` (only with `brief`) drops creators that do not fit and lists them in `data.brief.dropped_ids`; a creator that could not be judged is never dropped. `brief=` adds 2 credits, refunded when the judging step could not answer for every judged creator. These are signals to review, not a finding about the account. ### Creators in one market: `country=` Profile search matches account names, so a topic query returns accounts whose handle repeats it. To find the people who post about a topic in one market, add `country` (`CL`, `AR`, `MX`, `CO`, `PE`, `EC`, `UY`, `ES` or `BR`). The search then runs on what creators post there, on TikTok and Instagram: ```bash title="cURL" curl "https://www.socialcrawl.dev/v1/search/creators?query=inteligencia+artificial&country=CL&brief=Creators+who+publish+about+technology+and+AI&min_followers=5000" \ -H "x-api-key: YOUR_API_KEY" ``` The market's own name is added to your query (`inteligencia artificial` becomes `inteligencia artificial chile`). On TikTok, a creator is kept when one of the videos found is from that market and is about your query. On Instagram, the profiles a Google search from that market finds are each read from their About this account panel, and a creator is kept only when it declares that country. Every creator carries its follower count, `country` (`{ value, source }`, where source is `post_region` or `declared_country`) and `evidence`, the posts or profile text that found it, with links. `data.country` reports the query sent and, per platform, how many creators were kept and how many were dropped as another country, off topic or with no country declared. `min_followers`, `brief`, `sort` and `verified_only` work as before. The searches and lookups it runs are billed on top of the 10 (or 12) credits, each at its own price: 1 credit for the TikTok search page, 1 for the Google page and 1 for each Instagram profile read (at most 10, free for a profile read recently). `data.legs` lists each one with its credits. When no creator is found, the 10 are refunded and only the searches are billed. `sources` can name `tiktok`, `instagram` or both; any other source with `country` is a free 400, as is a market not on the list. ## One date vocabulary across the four lanes The lanes grew up separately and spell the same date window three ways: `search/everywhere` takes `from_date` and `to_date`, `search/news` takes `from` and `to`, and `search/forums` takes `timeframe` where `search/news` takes `time_range`. You do not have to remember which is which. Send whichever spelling you already have and it is translated to the one the endpoint declares, so a window carried from one lane to another is honoured rather than dropped. The values are still each endpoint's own. `timeframe` on `search/forums` accepts `all`, which has no `time_range` equivalent on `search/news`, so sending it there is a 400 that names the values that lane does accept. That is deliberate: a filter the endpoint cannot honour should say so rather than return an unfiltered page you paid for. ## News `/v1/search/news` plans one query into search angles, localizes them into the language of each requested country's Google News edition, and fans out the legs in parallel, returning one deduplicated article list with honest per-leg `query_source` provenance. Metered 2-14 credits. See the [full endpoint reference](/docs/search/news.md). ## Native search on several platforms `/v1/search/multi` sends one query to several platforms' own search endpoints in one call (TikTok, Instagram, YouTube, Reddit and Threads by default) and returns their rows together, each exactly as that platform's endpoint returns it plus `platform`. Each platform costs its own page price (1 credit, Telegram 2, LinkedIn 5), charged only when it came back with rows. Use it when you would otherwise call several search endpoints yourself; use `search/everywhere` when you want one planned, ranked answer. Metered 1-14 credits. See the [full endpoint reference](/docs/search/multi.md). ## All endpoints Looking for a cross-platform composite rather than a search? The [Prism family](/docs/prism.md) covers brand reputation, creator vetting, comment harvesting, and more. ## Platform notes - **Every result carries its source lineage**, so you always know which platform a candidate came from. - **`sources` and `exclude` are mutually exclusive** on every lane that accepts them. Passing both is a `400`. - All endpoints use `GET` with query parameters, authenticate with the `x-api-key` header, and return the unified SocialCrawl schema. ## Next steps - [Universal social search](/docs/search/everywhere.md): Parameters, streaming contract, billing, and response shape. - [Universal news search](/docs/search/news.md): Angle planning, per-country localization, and metered billing. - [Multi-platform search](/docs/search/multi.md): Each platform - [Prism](/docs/prism.md): Cross-platform composites for brand, creator, and commerce questions.