---
title: "Universal social search across 15 platforms"
method: GET
path: "/search/everywhere"
tags: ["search"]
---

# Universal social search across 15 platforms

`GET /search/everywhere`

## Request

- Base URL: `https://www.socialcrawl.dev/v1`
- URL: `https://www.socialcrawl.dev/v1/search/everywhere`
- Auth: API key in header `x-api-key`

Fans out a single query across Reddit, X (ai-search), YouTube, TikTok, Instagram, Hacker News, Polymarket, GitHub, Threads, Pinterest, LinkedIn, Rumble, Perplexity, and Tavily in parallel (17 sources, since TikTok, Instagram and YouTube each add a hashtag lane). A query that contains Hangul also runs `naver`: Naver blog, cafe and KnowledgeiN search in one lane, where Korean posts actually are; on other queries it runs only when you pass `sources=naver`. Naver rows carry the corpus in `metadata.corpus`; blog rows have the posting day, KnowledgeiN rows an estimated date (`date_confidence: low`) and cafe rows no date. Returns ranked + clustered results, enriched with **real-people comments** on the six lanes that have a comments surface: Reddit upvoted comments, Hacker News thread replies, YouTube, TikTok and Instagram top-liked comments, and GitHub issue discussion. The other lanes (X, Threads, Pinterest, LinkedIn, Rumble, Polymarket, Perplexity, Tavily) have no comments concept and their rows carry none, so read `top_comments` as absent rather than empty there. The comments per result live at `data.items[i].source_items[0].metadata.top_comments[]`, sorted by score descending, each `{ score, excerpt, truncated, author, url, date }`. Bodies are clipped to 300 characters on a word boundary; a clipped one ends with an ellipsis and sets `truncated: true`, so a short comment is never mistaken for a cut one. GitHub bot accounts are excluded from this block, so a CI deploy-preview or build-status comment never spends the budget. Attribution varies by lane, honestly: the Reddit, Hacker News, YouTube, TikTok, Instagram and GitHub lanes are post-shaped and carry an author and a date, while the Perplexity and Tavily lanes index the open web and have no author to give, so their rows are labelled with the source host. Expect 28 to 30 seconds for a full fan-out; allow a 60s client timeout. On the JSON path the X lane (`twitter-ai-search`, an AI-written synthesis of X posts that takes 15 to 45 seconds) runs only when it is the only source requested (`sources=twitter-ai-search`, or `x` / `twitter`); beside other sources it is not run, so it appears in `sources_failed` with a reason saying so and is left out of `sources_called` and `coverage`. Use the streaming path for the X synthesis alongside other sources, or `/v1/twitter/search/tweets` for X posts. Each row's `date_confidence` says how far to trust `published_at`: YouTube rows dated from a "3 years ago" or "2 months ago" label are `low`. Supports streaming via `Accept: text/event-stream` (emits `comments_enriched` chunks per candidate as enrichment lands, before the terminal `done`) and sync via `Accept: application/json`. Flat 20 credits per call regardless of enrichment.

## Query parameters

- `query` string, required
- `lookback_days` integer
- `from_date` string
- `to_date` string
- `sources` string
- `exclude` string
- `include_transcripts` boolean
- `relevance` 'filter'
- `include` string
- `judgments` 'on' | 'off'
- `switch_from` string

## Headers

- `Cache-Control` string
- `Idempotency-Key` string

## Response `200`

Successful response

- object
  - `success` boolean, required: Whether the request succeeded
  - `platform` string, required: Platform name
  - `endpoint` string, required: API endpoint path
  - `data` object, required: Platform-specific response data
    - `metrics` object: Key performance metrics
      - `total_views` integer: Total view count
      - `total_likes` integer: Total like count
      - `total_comments` integer: Total comment count
      - `engagement_rate` number: Computed engagement rate (0-1)
    - `period` string, nullable: Time period for the analytics data
    - `breakdown` object[], nullable: Per-item or per-period breakdown
    - `_warnings` string[]: Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'.
  - `credits_used` integer, required: Number of credits consumed
  - `credits_remaining` integer, nullable, required: Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.
  - `request_id` string, required: Unique request identifier for support
  - `cached` boolean, required: Whether the response was served from cache
  - `idempotent_replay` boolean: True only when this response is an idempotency replay
  - `meta` object: Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it.
    - `hint` object: One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces.
      - `code` string: creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat
      - `message` string: One sentence for a person or an agent to read.
      - `method` string: GET or POST.
      - `path` string: The call the hint points to.

## Other responses

- `400`: Invalid request - missing or malformed parameters
- `401`: Unauthorized - missing or invalid API key
- `402`: Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit
- `404`: Not found - the endpoint does not exist, or the requested resource was not found upstream
- `405`: Method not allowed - wrong HTTP verb for this endpoint
- `409`: Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation
- `410`: Gone - the discover run's retention passed and its rows were deleted; start a new run
- `413`: Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling
- `422`: Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC)
- `429`: Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.
- `500`: Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit
- `502`: Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge
- `503`: Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge
- `504`: Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After

---

[API](https://skmtc.dev/socialcrawl/apis/socialcrawl-api.md) · [All operations](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/revisions/a0ad2511004a?raw)