# SocialCrawl API: search endpoints # Base URL: https://www.socialcrawl.dev # Auth: x-api-key header # Full docs: https://www.socialcrawl.dev/docs/search ## GET /v1/search/everywhere Universal social search across 15 platforms Credit cost: 20 (override; tier standard) Parameters: - query (required): Search query (1-512 chars) - lookback_days (optional, integer): 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 (optional, string): 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 (optional, string): 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 (optional, string): 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 (optional, string): 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 (optional, string): 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.

.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 (optional, string): 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 (optional, enum: keep | drop): 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. - limit (optional, integer): 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 (optional, string): 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 (optional, string): Another name for sources, with the same values. When both are sent and differ, sources applies and `data._warnings` says so. - exclude (optional, string): 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 (optional, boolean): 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 (optional, enum: filter): 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. - include (optional, string): 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 (optional, enum: on | off): 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. - switch_from (optional, string): 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. curl -G "https://www.socialcrawl.dev/v1/search/everywhere" \ --data-urlencode "query=kanye west" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/search/forums Fused forum search across Reddit, Hacker News, and Naver 지식iN/카페, with top comments inline on hero threads by default. Credit cost: 10 (override; tier standard) Parameters: - query (required): Search query (2-256 chars), forwarded to every forum search. - sources (optional, string): Optional CSV allowlist of forum sources (reddit, hackernews, naver_kin, naver_cafe). Mutually exclusive with exclude. - exclude (optional, string): Optional CSV blocklist of forum sources. Mutually exclusive with sources. - comments (optional, string): Comment enrichment toggle (on|off, default on). 'off' returns thread-only. - timeframe (optional, string): Recency window passed to Reddit; HN filtered client-side (all|day|week|month|year, default all). - lookback_days (optional, integer): Alt recency window in days (1-365); HN filtered client-side. - relevance (optional, enum: score | filter): Optional. Without it every thread already carries items[].computed.relevance ({ p, sense, on_topic }: is the thread about what your query means, or a different thing that shares its words?), free, in the fused order (see judgments). score also reorders threads by relevance blended with their fused rank. filter also drops the threads that are not on topic, lists them in data.relevance.dropped_ids, and counts stance_split, question_share and top_communities over the threads it kept. A thread that could not be judged, or is too short to judge, is never dropped and carries relevance: null. Omit it to keep every thread in the fused order. Included in the flat 10 credits. - relevance_threshold (optional, string): Optional, only with relevance. The probability (0 to 1) a thread must reach to count as on topic. Default 0.5. Lower keeps more threads, higher keeps fewer. - judgments (optional, enum: on | off): Optional. on (default) or off. On, every thread also carries items[].computed.relevance ({ p, sense, on_topic }) from the same stance judgment, with data.relevance (mode default) counting it; the fused order is kept and nothing is dropped (relevance=score or filter reorders and drops). off returns the response without it. Included in the flat 10 credits. curl -G "https://www.socialcrawl.dev/v1/search/forums" \ --data-urlencode "query=airpods pro 3 battery" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/search/creators Fused creator discovery across TikTok, Threads, and Instagram, ranked by relevance, followers, and verification. YouTube, X, and Facebook people are opt-in via sources=. Credit cost: 10-24 (metered): 10 credits flat, with a coverage-based partial refund. A search no source has a creator for answers 200 with an empty `creators` and `empty_reason: no_matches`, at 0 credits. Adding brief= adds 2 credits, refunded when the judging step could not answer for every judged creator. With country=, the searches and lookups it runs are billed on top, each at its own endpoint's price: 1 credit for the TikTok search page, 1 for the Google page and 1 per Instagram profile looked up (at most 10, and free for a profile looked up recently), so at most 12 more. data.legs lists each one with its credits, and the 10 are refunded when no creator is found. A cached page is free. Parameters: - query (required): Niche or topic (2-256 chars), forwarded to every profile search. - sources (optional, string): Optional CSV allowlist of creator sources (tiktok, threads, instagram, youtube, twitter, facebook). Mutually exclusive with exclude. Omit to keep the default TikTok + Threads + Instagram walk. With country, only tiktok and instagram (the default), and any other source is a free 400. - exclude (optional, string): Optional CSV blocklist of creator sources. Mutually exclusive with sources. - min_followers (optional, integer): Drop fused creators whose follower count is below this integer floor. - verified_only (optional, boolean): When true, keep only verified creators after fusion. - sort (optional, enum: relevance | followers | verification): Which axis dominates rank: relevance (default), followers, or verification. - brief (optional, string): Optional. What you want to find, in your own words (3-300 chars), for example brief=Korean creators who review skincare products. The first 40 creators are judged from their name, handle and bio: does the account post about your brief (fits_brief, 0 to 1), and what kind of account is it (individual_creator, brand_or_business, media_or_publisher, fan_or_repost_page, cannot_tell; null when unsure). With sort=relevance (the default) they are re-ranked so creators who fit and are individual people lead; other sorts keep their order and only gain the labels. These are signals to review, not a finding. Adds 2 credits. - relevance (optional, enum: score | filter): Optional, only with brief. score (default) ranks and labels; filter also drops judged creators that do not fit the brief and lists them in data.brief.dropped_ids. A creator that could not be judged is never dropped. - judgments (optional, enum: on | off): Optional. on (default) or off. On, the first 40 creators also carry account ({ account_kind: individual_creator, brand_or_business, media_or_publisher, fan_or_repost_page, cannot_tell or null when unsure, account_kind_confidence, named_person }), judged from their name, handle and bio, and data.account_kinds reports how many were judged. The order is unchanged and it is free. off returns the response without it. - country (optional, enum: CL | AR | MX | CO | PE | EC | UY | ES | BR): Optional. Two-letter market code (CL, AR, MX, CO, PE, EC, UY, ES, BR) to find the creators who post about your query in that market, instead of searching account names. Runs on TikTok and Instagram: the market's name is added to your query, TikTok creators are kept when the video's own region is the market and its text is about your query, and Instagram creators when they declare that country on their About this account panel. Each creator carries country and evidence, and data.country reports the query sent and what was kept and dropped per source. The searches and lookups it runs are billed on top at their own price, at most 12 credits. Any other code is a free 400. Worth sending: - country=CL: Results for one country. curl -G "https://www.socialcrawl.dev/v1/search/creators" \ --data-urlencode "query=skincare routine" \ --data-urlencode "country=CL" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/search/multi One query, each platform's own search results, in one call at each platform's own price. Credit cost: 0-30 (metered): Metered, usually 1-14 credits: each platform is billed at its own endpoint's price, per platform, exactly as a direct call to that endpoint is billed (TikTok, Instagram, YouTube, Reddit, Threads, X and Facebook 1 credit a page, Telegram 2, LinkedIn 5). A platform whose page found nothing or failed costs nothing, and a platform page served from cache is free. A Threads phrase that Threads does not recognise is expanded into narrower searches, as on /v1/threads/search, and costs 1 credit per search that returned posts. With expand=context every platform runs your phrase plus expand_queries planned searches (3 by default, 3 at most), each billed as its own page, so the range above is multiplied by 1 plus expand_queries and the estimate quotes it that way. The searches inside a platform judge their rows for free; relevant_to= or label= is billed once on the request, for the rows of the merged page. data.sources..credits shows each platform's charge and credits_used the total. Relevance against your query (by default, or with relevance=) is free. Adding relevant_to= holds 8 extra credits and refunds down to 1 credit per started 25 rows that were newly judged: rows already judged for the same topic are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. The default labels (sponsored, intent, niche) are free. label=mention, quality, ai_style, ai_written, injection, or label=intent with offer=, holds 8 extra credits and refunds down to 1 credit per started 25 posts that were newly judged: posts already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. Parameters: - query (required): Keyword or phrase, sent unchanged to every platform (1-500 characters). Each platform matches it the way its own search endpoint does: Reddit matches any of the words unless you wrap a phrase in double quotes, and a phrase Threads does not recognise is expanded into narrower searches. - platforms (optional, string): Comma-separated platforms to search: tiktok, instagram, youtube, reddit, threads, twitter, facebook, linkedin, telegram. Default tiktok,instagram,youtube,reddit,threads. Each one costs its own endpoint's page price, and only when its page came back with rows. - since (optional, string): Keep only posts published on or after this date on every platform: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. A row with no date is kept. A platform page trimmed to nothing still costs its page, as it would on that platform's own endpoint. When you do not send a platform's own date filter, the narrowest one that reaches this date is sent for you on TikTok, YouTube and Reddit (an exact date on Threads, Facebook and X); data.window says which. - until (optional, string): Keep only posts published on or before this date on every platform: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. A row with no date is kept. Sent natively as Threads and Facebook end_date and the X until: operator; the other platforms have no upper bound of their own, so their newer rows are dropped from the page and still cost the page. Use since and until together for a calendar month. - expand (optional, enum: context): Optional. context also searches up to three short phrases written from your query and, when you send it, relevant_to: the words the people who wrote the posts actually use. Native search reads a query literally, so a long phrase such as fake byd spare part sellers scam misses a seller who writes BYD spare parts Sharjah. Your own query always runs as well. Every row carries matched_query, the search that found it; data.expansion lists the searches with the rows each one added and its credits; data.sources..by_query has each search's own cursor. Each extra search is billed on each platform exactly like your query (1 credit a page with rows, LinkedIn 5), and writing the searches is free. If they cannot be written in time, one search is made from the product words in your query (data._warnings says expand_fallback), or, when there are none to drop, only your query runs (expand_unavailable). Each search on each platform is one in-flight request on your API key, so one expanded call on six platforms holds up to 24 of the key's 50 at once; a search the limit refuses costs nothing and data._warnings says searches_limited. - expand_queries (optional, integer): Optional, only with expand=context. How many extra searches to run, 1 to 3 (default 3). Each one can cost up to one more page per platform. - tiktok.date_posted (optional, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time): TikTok only. Sent to /v1/tiktok/search as `date_posted`, exactly as that endpoint takes it. One of: yesterday, this-week, this-month, last-3-months, last-6-months, all-time. - tiktok.sort_by (optional, enum: relevance | most-liked | date-posted): TikTok only. Sent to /v1/tiktok/search as `sort_by`, exactly as that endpoint takes it. One of: relevance, most-liked, date-posted. - tiktok.region (optional, string): TikTok only. Sent to /v1/tiktok/search as `region`, exactly as that endpoint takes it. - instagram.date_posted (optional, enum: last-week | last-month | last-year): Instagram only. Sent to /v1/instagram/search/reels as `date_posted`, exactly as that endpoint takes it. One of: last-week, last-month, last-year. - instagram.include (optional, enum: creator): Instagram only. Sent to /v1/instagram/search/reels as `include`, exactly as that endpoint takes it. One of: creator. - youtube.uploadDate (optional, enum: today | this_week | this_month | this_year): YouTube only. Sent to /v1/youtube/search as `uploadDate`, exactly as that endpoint takes it. One of: today, this_week, this_month, this_year. - youtube.sortBy (optional, enum: relevance | popular): YouTube only. Sent to /v1/youtube/search as `sortBy`, exactly as that endpoint takes it. One of: relevance, popular. - youtube.type (optional, enum: videos | shorts): YouTube only. Sent to /v1/youtube/search as `type`, exactly as that endpoint takes it. One of: videos, shorts. - youtube.duration (optional, enum: under_3_min | between_3_and_20_min | over_20_min): YouTube only. Sent to /v1/youtube/search as `duration`, exactly as that endpoint takes it. One of: under_3_min, between_3_and_20_min, over_20_min. - youtube.region (optional, string): YouTube only. Sent to /v1/youtube/search as `region`, exactly as that endpoint takes it. - reddit.sort (optional, enum: relevance | new | top | comment_count): Reddit only. Sent to /v1/reddit/search as `sort`, exactly as that endpoint takes it. One of: relevance, new, top, comment_count. - reddit.timeframe (optional, enum: all | day | week | month | year): Reddit only. Sent to /v1/reddit/search as `timeframe`, exactly as that endpoint takes it. One of: all, day, week, month, year. - threads.start_date (optional, string): Threads only. Sent to /v1/threads/search as `start_date`, exactly as that endpoint takes it. - threads.end_date (optional, string): Threads only. Sent to /v1/threads/search as `end_date`, exactly as that endpoint takes it. - twitter.sort (optional, enum: latest | top): X only. Sent to /v1/twitter/search/tweets as `sort`, exactly as that endpoint takes it. One of: latest, top. - facebook.start_date (optional, string): Facebook only. Sent to /v1/facebook/search/posts as `start_date`, exactly as that endpoint takes it. - facebook.end_date (optional, string): Facebook only. Sent to /v1/facebook/search/posts as `end_date`, exactly as that endpoint takes it. - facebook.recent_posts (optional, boolean): Facebook only. Sent to /v1/facebook/search/posts as `recent_posts`, exactly as that endpoint takes it. - facebook.location_uid (optional, string): Facebook only. Sent to /v1/facebook/search/posts as `location_uid`, exactly as that endpoint takes it. - linkedin.sort_by (optional, enum: date_posted | relevance): LinkedIn only. Sent to /v1/linkedin/search/posts as `sort_by`, exactly as that endpoint takes it. One of: date_posted, relevance. - linkedin.date_posted (optional, enum: past_24h | past_week | past_month): LinkedIn only. Sent to /v1/linkedin/search/posts as `date_posted`, exactly as that endpoint takes it. One of: past_24h, past_week, past_month. - linkedin.content_type (optional, enum: videos | photos | jobs | live_videos | documents | collaborative_articles): LinkedIn only. Sent to /v1/linkedin/search/posts as `content_type`, exactly as that endpoint takes it. One of: videos, photos, jobs, live_videos, documents, collaborative_articles. - telegram.date_posted (optional, enum: last-hour | last-day | last-week | last-month | last-year): Telegram only. Sent to /v1/telegram/search as `date_posted`, exactly as that endpoint takes it. One of: last-hour, last-day, last-week, last-month, last-year. - telegram.region (optional, string): Telegram only. Sent to /v1/telegram/search as `region`, exactly as that endpoint takes it. - relevance (optional, enum: score | filter): Optional. Without this param every row already carries computed.relevance against your query, free ({ p, sense, depth, spam }: is this row about what your query means, or a different thing that shares its words?), and nothing is dropped or reordered. score asks for it explicitly and waits for every row; filter also drops the rows that are not about your query, and lists their ids in data.relevance.dropped_ids. Your query is the topic; nothing to configure. A row that could not be judged is never dropped and carries relevance: null. Pagination is unchanged, so a filtered page can hold fewer rows. Free with your query as the topic; with relevant_to it adds 1 credit per started 25 newly judged rows (rows already judged for the same topic are free, and so is a cached page). - relevance_threshold (optional, string): Optional, only with relevance. The probability (0 to 1) a row must reach to be kept by relevance=filter. Default 0.5. Lower keeps more rows, higher keeps fewer. - relevant_to (optional, string): Optional, only with relevance. Up to 200 characters describing what you mean, used as the topic instead of the query. Use it when the query is ambiguous, for example query=cleopatra with relevant_to=Cleopatra, the IGT slot game. - judgments (optional, enum: on | off): Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same. - dry_run (optional, enum: 1): Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged. - fit (optional, enum: goal): Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged. - goal (optional, string): Required by fit=goal. What you are trying to do, in your own words, up to 300 characters. - fit_tokens (optional, integer): Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it. - label (optional, string): Optional CSV of SocialCrawl labels to add to every post. Without this param every page already carries sponsored, intent and niche, free; label= adds the labels you name to them (the defaults keep running). sponsored, intent and niche are free when asked for too; mention, quality, ai_style, intent with offer=, and injection add 1 credit per started 25 newly judged posts. judgments=off (or label=none) turns the default labels off. sponsored: is the post a paid or gifted promotion (p, 0 to 1), did it carry a disclosure marker such as #ad or 광고 (disclosed), is it likely paid with no marker (undisclosed), and which of the accounts it mentions does it promote (brand, or null). These are signals to review, never a finding. mention (needs brand=): is the post about that brand rather than something that shares its name (about_brand, 0 to 1), how it feels about the brand on five levels (sentiment_level 0 to 4 and sentiment_score 0 to 1, null when the post is not about the brand), is it sarcastic, which aspect it talks about (taste_or_quality, price_or_value, availability_or_delivery, health_or_safety, advertising_or_campaign, customer_service, none), and did the author buy or use it (first_hand). intent: what the author is mainly doing (label: asking_for_recommendation, comparing_options, switching_away, complaining, promoting, news_or_discussion, other, or null when unsure, with confidence), whether they read as a potential buyer rather than a seller (buyer, seller), how pressing the need is (urgency, 0 to 3), and, when you pass offer=, whether your offer would plausibly help them (fits_offer). niche: which of the 33 niches of the published taxonomy sc-niche-v1 the caption belongs to, or personal_no_niche, or other (label, confidence, taxonomy), with label null when the caption is too thin to tell or the pick is unsure. It reads the caption only, not the video. quality: how much checkable detail the caption carries (fact_density 0 to 3), whether it mainly asks for likes, replies, shares, follows or tags (engagement_bait, 0 to 1), whether it is written to provoke anger as a way to get engagement (rage_bait, 0 to 1; about the writing, never the side taken), whether it only repeats someone else's news or view (secondhand, 0 to 1), and what the post is mainly doing (post_aim: inform, opinion, sell, entertain, provoke, other). exclude=engagement_bait drops posts whose engagement_bait is 0.8 or higher. ai_style: writing patterns common in AI-generated text, judged on the text alone. It does not say who wrote the post, and a person who writes in this style is flagged too. Six patterns are judged, each a probability (0 to 1): binary_contrast ("This is not X. It's Y."), faux_insight ("Here's what nobody tells you" and throat-clearing openers), colon_reveal ("The best part: it learns."), profound_kicker (ends on an aphorism or mic-drop line), puffery ("marks a pivotal moment", "highlighting the importance of") and rhetorical_setup ("What if I told you", a question the post answers itself, "Not a X. Not a Y. A Z."). Four are counted in the text: slop_words (words and phrases such as delve, leverage, robust, game changer, at the end of the day), em_dashes, emoji_bullets (lines that start with an emoji or a symbol bullet) and one_line_paragraphs (paragraphs that are one short line). pattern_count is how many patterns are present (a judged pattern at 0.8 or higher, slop_words 1 or more, em_dashes 2 or more, emoji_bullets 2 or more, one_line_paragraphs 5 or more) and markers lists their names, comma-separated. A post with less than about eight words of text is only counted, with every judged pattern 0. The judged patterns read the first 400 and the last 150 characters of a long post, and the counts read the whole post. exclude=ai_style drops posts with 2 or more patterns. ai_written: how likely the post was written by an AI model, from SocialCrawl's own text classifier, reading the opening of the post (about 1,000 characters): p (0 to 1, calibrated), level (likely (p 0.95 or higher), possible (p 0.71 or higher) or unlikely) and model (the model name; a new name means a new scale). A post under 8 words is too short to read: p null, level too_short. It is a probability, not proof: a person can be flagged and an AI-written post can pass, and the shorter the post the less certain it is. exclude=ai_written drops likely posts. injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. A post that could not be judged carries labels: null. Posts already labelled for anyone are free, and so is a cached page. data.labels reports what was judged and billed. - exclude (optional, string): Optional CSV (engagement_bait, ai_style, ai_written). engagement_bait, only with label=quality, drops posts whose engagement_bait probability is 0.8 or higher. ai_style, only with label=ai_style, drops posts that show 2 or more of its writing patterns (pattern_count 2 or higher). ai_written, only with label=ai_written, drops posts whose level is likely (p 0.95 or higher), or whose p reaches your ai_written_threshold; a post too short to read is never dropped. Dropped posts are listed in data.labels.dropped_ids. A post that could not be judged is never dropped. - ai_written_threshold (optional, string): Optional, only with label=ai_written and exclude=ai_written. The p (0 to 1) at which exclude=ai_written drops a post. Default 0.95 (level likely). 0.71 also drops possible posts: more AI posts go, and more posts by people with them. - brand (optional, string): Required by label=mention, ignored otherwise. The brand or product the posts are judged against, up to 300 characters, for example brand=Buldak. Without it label=mention is skipped with the warning label_mention_needs_brand and is not billed. - brand_description (optional, string): Optional, with label=mention. One plain sentence saying what the brand is, for example brand_description=Samyang's spicy instant noodle brand. Use it when the name is also an ordinary word or another company's name. - offer (optional, string): Optional, with label=intent. One or two plain sentences saying what you sell, up to 300 characters, for example offer=A web design agency that builds websites for small businesses. Adds fits_offer to every post; without it fits_offer is null. - label_evidence (optional, enum: 1): Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it. Worth sending: - label=sponsored: Marks each post that is paid or sponsored, at no extra credits; intent and niche are free too. - relevance=filter: Drops rows that are not about your query, at no extra credits; relevance=score keeps them and adds a score. - since=2026-09-01: Returns only posts after this date, so a daily poll pays only for the pages with new posts. curl -G "https://www.socialcrawl.dev/v1/search/multi" \ --data-urlencode "query=matcha latte" \ --data-urlencode "label=sponsored" \ --data-urlencode "relevance=filter" \ --data-urlencode "since=2026-09-01" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/search/news Planned multi-country news search: one query, localized and fanned out across two independent news indexes in a single call. Credit cost: 2-62 (metered): 2 credits + 1 credit per google leg that returns at least one article (upfront hold 2 + min(5 x countries, max_legs, 12), maximum 14 on the default engine). Adding the bing engine adds 1 credit per 5 articles it returns, because that engine is priced per article rather than per call; the absolute ceiling with both engines is 62. The hold always settles down to the actual charge, and empty, skipped or failed legs bill 0. Parameters: - query (required): News topic or question (1-500 chars). Boolean AND/OR/NOT and quoted phrases are supported; Google advanced operators (site:, intitle:, before:) are rejected. - countries (optional, string): CSV of ISO 3166-1 alpha-2 country codes to search (1-12 of the 50 supported editions, default US). Each country searches its news edition in its default language; duplicates collapse. - engines (optional, string): CSV of news indexes to search: google (default) and bing. Asking for both runs the same plan on each and merges the results, which roughly doubles distinct articles and adds a snippet to most rows. The bing engine serves 49 of the 50 editions (not CN) and is priced per article; `publisher` and `from`/`to` are google-only. - sort (optional, enum: relevance | date): Ordering of the merged articles: relevance (default, each engine's own ranking) or date (newest first, undated articles last). - time_range (optional, enum: day | week | month | year): Recency window (day | week | month | year, default day). Ignored when from/to is present. - from (optional, string): Lower publish-date bound, YYYY-MM-DD or Unix seconds. Pins every leg to the primary news source. - to (optional, string): Upper publish-date bound, YYYY-MM-DD or Unix seconds. Pins every leg to the primary news source. - publisher (optional, string): Bare publisher domain filter (e.g. bbc.com; no scheme or path). Pins every leg to the primary news source. - depth (optional, integer): Articles requested per leg (10-100 in steps of 10, default 10). The google engine is priced per call, so depth is free there; the bing engine is priced per article and caps its own legs at 20. - max_legs (optional, integer): Hard cap on billable legs (1-12, default 12). The upfront hold shrinks with it. - group (optional, enum: stories): Optional. stories groups the articles that report the same event across editions, outlets and languages into data.stories[] ({ id, head_id, member_ids, size, outlets, outlet_count, countries, languages, first_seen, last_seen, judged }), where every id is an article's canonical_url (or url). items[] and its order are unchanged. data.story_grouping reports how many articles were judged and what it cost. An article that could not be judged is its own story with judged: false; if grouping is unavailable, stories is null and data._warnings says stories_unavailable. JSON responses only (ignored on the event stream). Grouping is on by default now (see judgments); group=stories asks for it explicitly with a longer time budget. Free. - judgments (optional, enum: on | off): Optional. on (default) or off. On, JSON responses also carry data.stories and data.story_grouping (see group), grouped under a short time budget; when grouping does not finish in time, stories is null and data._warnings says stories_pending (stories_unavailable when it failed). items[], their order and the price are unchanged. off returns the response without them. curl -G "https://www.socialcrawl.dev/v1/search/news" \ --data-urlencode "query=samsung galaxy launch" \ -H "x-api-key: YOUR_API_KEY"