# 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. 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. ## 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 | `query`, `lookback_days`, `from_date`, `to_date`, `sources`, `exclude` | | `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 | `query`, `sources`, `exclude`, `comments`, `timeframe`, `lookback_days` | | `GET /v1/search/creators` | 10 | Fused creator discovery across TikTok, Threads and Instagram, ranked by relevance, followers and verification | `query`, `sources`, `exclude`, `min_followers`, `verified_only`, `sort` | | `GET /v1/search/news` | 2-14 metered | One query planned into angles, localized per country edition, and merged into one deduplicated article list | `query`, `countries`, `time_range`, `from`, `to`, `publisher`, `depth`, `max_legs` | ## Universal social search `/v1/search/everywhere` fans out across 14 platforms in parallel, and up to 17 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. Real-people sentiment, not just titles. 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. `/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. ## 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). ## 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. - [Prism](/docs/prism.md): Cross-platform composites for brand, creator, and commerce questions.