Universal Search

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

curl "https://www.socialcrawl.dev/v1/search/everywhere?query=best+noise+cancelling+headphones" \
  -H "x-api-key: YOUR_API_KEY"

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 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.

Pick a lane

Every lane adds its judgments by default at no extra credit, and judgments=off returns the response without them. Labels documents the field shapes and how each was measured.

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.

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.

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".

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:

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.

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.

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, 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-12 credits. See the full endpoint reference.

All endpoints

5 endpoints available.

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