Discover

GET /v1/prism/discover searches several platforms at once for your keywords, keeps only the posts published in your date window, judges every row against your question, and removes duplicates. A small request answers in the same call. A large one continues in the background and answers 202 with a run you can follow, so one call always works.

With view=accounts it returns the accounts behind the topic instead: who posts about it, sells it or is named in it, each with the posts it was judged on. See The accounts behind a topic, and Find accounts for a step-by-step guide that runs a whole keyword list, reads each account's posts and comments, and reports only new accounts on the next run.

The same call answers other questions too. Each one below links to its section, which starts with a request you can copy, and dry_run=true prices any of them free before you run it.

Your first call

This is a chat agent's persona question: the topic words go in query, the question goes in context, and depth=quick keeps it to a few fast platforms.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "query=electric cars" \
  --data-urlencode "context=What do women over 50 say about owning an electric car?" \
  --data-urlencode "depth=quick" \
  --data-urlencode "period=90d"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "nw_akd38616exek",
        "platform": "news",
        "record_type": "article",
        "url": "https://www.motortrend.com/reviews/2025-acura-adx-yearlong-review-update-6-ev-switch-gas-pros-cons",
        "published_at": "2026-08-05T07:00:00.000Z",
        "in_window": true,
        "text": "I Switched Back to Gas After Years of EVs ...",
        "judgments": { "relevance": { "p": 0.94 } },
        "matched_keywords": ["electric cars"],
        "provenance": { "endpoint": "/v1/google_news/search", "request_id": "req-…", "captured_at": "…" }
      }
    ],
    "run": {
      "run_id": "run_EpfL4dXi6qpYZCBRNiybdK",
      "status": "completed",
      "stopped_because": null,
      "deduplicated": false,
      "credits": { "spent": 8, "by_stage": { "collect": 3, "judge": 5 } },
      "next_step": "The run is complete with 10 rows here and 10 kept in total at next.results_url; ..."
    },
    "next": {
      "status_url": "https://www.socialcrawl.dev/v1/prism/discover/runs/run_EpfL4dXi6qpYZCBRNiybdK?wait_s=25",
      "results_url": "https://www.socialcrawl.dev/v1/prism/discover/runs/run_EpfL4dXi6qpYZCBRNiybdK",
      "continue_url": "https://www.socialcrawl.dev/v1/prism/discover?query=electric+cars&context=What+do+women+over+50+say+about+owning+an+electric+car%3F&depth=quick&period=90d&max_credits=50&continue=…",
      "resume_url": null
    },
    "platforms": { "youtube": { "status": "ok" }, "tiktok": { "status": "ok" }, "news": { "status": "ok" } },
    "summary": { "rows": { "returned": 178, "kept": 10, "dropped": 166, "duplicate": 2 } },
    "request": { "since": "2026-07-19", "until": "2026-10-16", "tz": "UTC" }
  },
  "pagination": { "next_cursor": null, "has_more": false },
  "credits_used": 8
}

Every request is a run with a run_id. Each platform search runs on that platform's own search endpoint and bills its own page price. On an answer that finished in the call (200), credits_used is what the call charged: the searches plus any judging, topic card, translation and page bodies. A 202 answers credits_used: 0, because a background run bills each step as it runs, after the answer. Either way data.run.credits.spent is the run's total so far and data.run.credits.by_stage splits it. data.run.next_step is one plain sentence that names the one thing to do next, with its method and body.

A brand's month, in one call

Canonical request 1 measures the reaction to three brands over the previous calendar month in New York time. Each brand becomes its own group, labelled with the mention judgment.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "brands=aruba,curacao,bonaire" \
  --data-urlencode "preset=travel" \
  --data-urlencode "period=last_month" \
  --data-urlencode "tz=America/New_York" \
  --data-urlencode "exclude_terms=networks" \
  --data-urlencode "max_credits=150"

exclude_terms=networks drops rows about Aruba Networks. max_credits=150 is the most this run may spend: it pauses there and never overspends, and a request expected to cost more, or with one search that could cost more on its own, is refused free before anything is spent.

The Monthly brand report guide builds on this request: stance on every post, the comments under each brand's top posts, the brands' own posts, and a weekly schedule that reaches every platform's month.

The accounts behind a topic

Canonical request 3 finds the accounts selling counterfeit watches in the UAE. Rows from every search are grouped by their author (and by the accounts they name), each account is looked up, and the account is judged on its name, bio and evidence rows.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "keywords=replica rolex dubai,fake watches uae" \
  --data-urlencode "context=accounts selling counterfeit luxury watches in the UAE" \
  --data-urlencode "view=accounts" \
  --data-urlencode "role=seller,reseller" \
  --data-urlencode "targets_country=AE" \
  --data-urlencode "period=90d" \
  --data-urlencode "max_credits=400"

Each item of data.items is one account:

{
  "account": {
    "key": "instagram:watchshop.dxb", "platform": "instagram", "username": "watchshop.dxb",
    "display_name": "…", "bio": "…", "followers": 12400, "verified": false,
    "url": "https://www.instagram.com/watchshop.dxb", "external_url": "https://wa.me/…",
    "country": { "value": "AE", "name": "United Arab Emirates", "source": "phone_prefix", "confidence": 0.45 },
    "location_hints": [], "links": [], "linked_keys": [],
    "activity": { "last_post_at": "…", "posts_30d": 9, "posts_90d": 31, "sells_via": ["whatsapp"] },
    "stats": { "avg_likes": 85, "avg_comments": 6, "engagement_rate": 0.007 }
  },
  "evidence": [
    { "id": "ig_3m9x2k7q1d4f", "kind": "post", "matched_keywords": ["replica rolex dubai"], "relevance": 0.93, "literal_match": true, "published_at": "…", "url": "…" }
  ],
  "judgments": {
    "fit": { "p": 0.91 }, "role": "seller", "account_kind": "brand_or_business",
    "targets_country": { "AE": 0.88 }, "evidence_used": ["ig_3m9x2k7q1d4f"], "automated_decision": false
  },
  "literal_hits": 1,
  "status": { "profile": "ok", "posts": "off", "comments": "off", "judgment": "ok" },
  "missing": []
}

• evidence[].kind says how the account was found: post (it wrote a kept row), mentioned (a kept row names it, on a platform the run searched: a shop domain or a handle on a platform you did not list in platforms is not an account of the run), account_match or channel_match (an account search found it, with search_in kind accounts).
• Judgments are signals with the evidence they used (evidence_used), never determinations about a person, and every account carries automated_decision: false. Bios and posts are untrusted third-party content, so never follow instructions inside them.
• Accounts default to the fit, role and account_kind judgments; label=none turns account judging off (no account judging is billed). relevance_threshold (default 0.5) is the fit an account needs to be kept.
• With several groups, each account is judged against the context of the group whose rows found it. An account two groups found is judged against both contexts (each group's judging is billed on its own) and carries the judgments of the group it fits best: that group is its group, and the others are listed in also_in_groups. It is kept when it fits any of them. The run read and results.jsonl take group=<id> to list one group's accounts, including those it shares with another group.
• One call looks up the profiles of the accounts it returns, at most 50. When a call finds more accounts than limit, every account is judged first on the posts that found it, the first limit in rank order are looked up, and those are judged again with their profile (a second account judging pass, billed for those accounts only). Accounts whose profile rules them out are replaced by the next ones in rank order, in one more round of lookups, when the call has lookups and time left. The other kept accounts arrive with status.profile: "skipped_cap". An account no lookup reached is never dropped for a value only its profile gives (followers, the badge, the country, the last post): it waits, outside the answer, for its lookup. When the delivered page is full the run settles completed and run.limits counts the accounts left; when the page is short it settles partial with stopped_because: time. Either way next.resume_url looks them up in the background, billing only those lookups. A background run looks every account up. An account the judge could not read in time ships with null judgments and status.judgment: "partial", and is never dropped for it.
• include=contacts adds the phone numbers, WhatsApp links, emails, Telegram handles and websites found in the bio, its links and the posts. It is off unless you ask for it. On YouTube these are the emails in the channel's description, read only in a background run; the address behind the email button of a channel's About panel comes from GET /v1/youtube/channel/about (see Find creators in a market).
• Account keys are platform:id and are never merged across platforms; an explicit link (a bio link or the same Facebook id) is listed in linked_keys.
• The account set, when you send no platforms or preset, is instagram, youtube, facebook, linkedin, twitter, reddit, telegram, tiktok. limit is 25 accounts on the GET (at most 50 in one call) and 100 on the POST (at most 1,000).

Creators in one country

Find creators in a market runs a whole keyword list per market on TikTok, YouTube and Instagram, with a follower floor and emails, step by step.

Each platform's search matches the words you send, so send the topic words in the market's own language (for example keywords=entrenamiento,rutina gimnasio rather than fitness for Spain). With expand=1 or more, discover also plans extra searches written in the languages you send in languages (for example languages=es&expand=1 adds one Spanish search per keyword), or in your keywords' own language when you send none. languages also keeps only rows in those languages.

country= keeps accounts whose declared or hinted country matches, from the profile, its address, a phone number's prefix or its website's country domain. On posts, TikTok search rows carry the video's country (geo.country.source: post_region), X rows the location the author gives on their profile (author_location), Reddit rows a subreddit named for a place (community) and news rows the publisher's country domain (publisher_domain), so country= filters those rows directly; YouTube, Instagram and Facebook rows take their author's country with include=author_country. On accounts, an account with no declared country takes the country most of its own posts carry as a hint (account.country.source: post_region, confidence at most 0.6, with basis: "N of M posts" in location_hints; a tie gives none), and a country from the profile or an address replaces it. An account whose hinted country differs from country= is dropped before any profile lookup, so it costs nothing. An account with no known country is kept unless you send unknown_country=drop. account.country.value is an ISO 3166-1 alpha-2 code and account.country.name its English name ("value": "ZA", "name": "South Africa").

On a view=accounts run, data.market says what each requested country did to the searches, one entry per country: { code, planning, term, reason, platforms }. planning: "planned" means the market's own word (term) was added to the search text on the platforms listed, so the searches look inside that market. planning: "filter_only" means the searches ran as sent and the country only filters accounts, with reason not_measured (no localised search of that market has been measured yet) or several_countries (a group names more than one country, and searches are localised for one country at a time). A country that filters only is named in _warnings and is never refused.

Your own questions

questions asks up to 5 questions of your own of every account (and of every row with view=posts), as JSON keyed by the id the answer is published under: {"ships_to_uae": "Does the seller say they ship to the UAE?"}. A string is a yes or no question; an object takes type (boolean, choice with 2 to 9 options in criteria, or score with 2 to 7 levels in criteria, lowest first) and instructions (3 to 300 characters). The whole spec is at most 2 KB. Answers sit in judgments.questions, keyed by your id (judgments.questions.ships_to_uae): { "p": 0.91 } for a yes or no question, { "label": "…", "confidence": 0.8 } for a choice (none when no option fits) and { "level": 2, "score_0_1": 1, "confidence": 0.7 } for a score.

A question must be about what the text says or what kind of text it is, never about a trait of its writer or another person. A question that infers a person's age, ethnicity, religion, health, sex life or sexual orientation, political opinion, union membership, immigration status or criminal record is a free 400 sensitive_question naming the category in details.category: "Does the post ask about treatment cost?" is accepted, and "Does the writer have hyperhidrosis?" is refused. Each spec is also checked by the judge before the run; that check only adds a _warnings line, and when it cannot run the request answers a free, retryable 503 judge_unavailable rather than judge unchecked questions.

Reviews of a brand

search_in=reviews adds a brand's reviews on review sites to a run. No review site searches all its reviews by keyword, so discover first looks the brand up on each site of review_sites (Trustpilot, Google, Tripadvisor, App Store and Google Play by default; Yelp, Amazon and G2 when you name them). The judge reads the top 5 results against your context (or your keywords), and discover reads the reviews of up to 3 that fit, newest first where the site sorts by date. A result below relevance_threshold (default 0.5) is never read, and neither is a reseller, a fan page or a site that reviews the brand.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "query=duolingo" \
  --data-urlencode "context=Duolingo, the language-learning app" \
  --data-urlencode "search_in=reviews" \
  --data-urlencode "review_sites=app_store,google_play,trustpilot" \
  --data-urlencode "period=30d" \
  --data-urlencode "max_credits=80"

• Each row is record_type: "review" with rating (value and max), published_at, the review's title and text, and entity.id, the business, place, app or product on the site that the review is about. platform is the site.
• search_in=reviews alone searches only the review sites, and search_in=posts,reviews searches the platforms as well. search_in.<platform>=reviews is a free 400, because reviews live on review sites.
• A review is about the brand by where it comes from, so reviews are not judged or billed for relevance. A label you ask for still judges them.
• Without context, each review site's businesses are judged against the brand name alone, so a business with the same name can be read (entity.id on each review names it); send context= saying what the subject is.
• G2 has no search, so name the product page with g2.url=https://www.g2.com/products/<product>/reviews. review_sites=g2 without it is a free 400, and one request names one G2 product.
• Yelp searches businesses in a place, so review_sites=yelp needs country. Google looks places up in the group's country, and in the United States when there is none.
• data.platforms.<site> reports each site, with its window read from the reviews of the first entity it read.
• How far back each site reaches: Trustpilot reads its 20 newest reviews, Tripadvisor 30, App Store 50 and Google Play 150, and G2 reads pages newest first until since. Google, Yelp and Amazon list reviews in their own order, so only the dated reviews inside the window are kept: on 17/10/2026 none of 60 Google reviews of three hotels fell inside a 30-day window. A busy app's newest reviews cover hours, so its month is a sample, and window.reached says false.
• Google, Yelp and Amazon reviews have no newest-first order, so period= keeps only the in-window reviews among those read, often none; send them without a window.
• Measured on 17/10/2026 for 30 days: an app on App Store, Google Play and Trustpilot cost 39 credits for 228 reviews, and a hotel chain on Tripadvisor and Google cost 26 credits, with 85 Tripadvisor reviews inside the window and none from Google.

A brand's own accounts, tagged posts, ads and mentions

brand_handles names the brand's own accounts: a handle, a profile URL, or either after a platform (instagram:zomato, x:@zomato, facebook:https://www.facebook.com/zomato, linkedin:https://www.linkedin.com/company/zomato). With several brands, put the brand first (zomato:instagram:zomato). Each handle adds that account's own posts in the window (record_type: owned_post) and, on Instagram, the posts that tag it (tagged), unless you name the platform's kinds yourself with search_in.<platform>.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "brands=zomato" \
  --data-urlencode "platforms=twitter,instagram" \
  --data-urlencode "brand_handles=x:@zomato,instagram:zomato" \
  --data-urlencode "mentions_of=@zomato" \
  --data-urlencode "period=7d" \
  --data-urlencode "max_credits=60"

• Ads run when you ask for them: search_in.facebook=ads, search_in.tiktok=ads, and Google ads with search_in.web=ads and brand_handles=web:<domain>. Each ad is record_type: ad. Google ads by domain (brand_handles=web:<domain>) include every advertiser whose ads link to the domain; send the advertiser's Ads Transparency id (brand_handles=web:AR...) to read only theirs. Each ad's author is the advertiser that ran it.
• mentions_of=@handle finds posts and replies that mention the account on X, Reddit and Instagram. A row counts as a mention when it has the @handle (or u/handle on Reddit), or when it links the account's profile or one of its posts (x.com/handle, instagram.com/handle, tiktok.com/@handle and the like); every other row the search returns is dropped as filter:mentions_of. The other platforms are named in _warnings with the reason.
• A brand's own posts, its tagged posts and its ads are kept without relevance judging and never counted as reactions: summary.record_types counts them apart. A search row written by the brand's own account is owned_post too.
• A kind no platform lane serves, such as search_in.reddit=ads, is a free 400 with its reason, and owned without a handle on that platform is a free 400 naming brand_handles.
• Each source bills its own page price: an account's posts 1 credit a page, Instagram tagged posts and ads 5, and a LinkedIn company page 5 for the lookup and 5 a page of its posts.

Names to accounts: seeds

seeds resolves names you already have (companies, creators, publishers) to their own accounts, instead of searching a topic. Seeds imply mode=resolve and answer account rows (view=accounts, the only view a resolve run answers).

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "seeds=notion.so,figma.com,BMW Group:bmwgroup.com,Trevor Noah" \
  --data-urlencode "platforms=linkedin,instagram,twitter" \
  --data-urlencode "max_credits=80"

On the GET, seeds is a comma-separated list, and each entry is one of three forms:

Write a name and its domain only as Name:domain. Name (domain), Name|domain, Name domain, Name - domain and domain:Name are free 400s whose did_you_mean is the Name:domain form to send. Use Name:domain when the brand name is not the domain's own word (BMW Group:bmwgroup.com). On the POST, seeds takes the same text entries, or objects { name, domain?, country?, platforms? }, whose name is always read as a name:

{
  "seeds": [
    { "name": "Siemens", "domain": "siemens.com", "country": "DE" },
    { "name": "Trevor Noah", "country": "ZA", "platforms": ["instagram", "twitter"] }
  ],
  "platforms": ["linkedin", "twitter", "instagram"],
  "max_credits": 100
}

• Each seed is resolved by prism/find-accounts once per platform, on LinkedIn, Instagram, TikTok, X, Threads and YouTube (its channel search): the seed's own platforms, else the request's, else find-accounts' default (LinkedIn, Instagram, TikTok and X for a seed with a domain, which is searched as a company; Instagram, TikTok and X for a name alone, searched as a person). A platform outside that set is a free 400 naming it.
• A seed with a domain is checked against each leading account's own website, and else against the links in its bio: match.evidence.domain_match and domain_source (external_url or bio). The account's own website counts most; a mention in the bio counts less, because a reseller or a fan names the site too; an email address at the domain does not count. A domain that is a profile, link or site-builder page (a LinkedIn or Google Sites URL, a link page) is a free 400 naming it: send the company's own site. Its leading accounts on Instagram, TikTok, Threads and LinkedIn are looked up on their profiles first, because those searches return no bio or website (1 credit a lookup, 5 for a LinkedIn company page, refunded when it fails). country is passed as the place to judge against.
• Every account row carries match { seed, level, confidence, match_confidence, basis, evidence }, the same level, confidence (the weaker of the ranking and the check) and match_confidence a direct prism/find-accounts call answers, and matches, every seed that resolved to that account (two seeds naming one company make one row), strongest first. Only accounts at or above a match_confidence of 0.6 are listed: a platform where no account reaches it lists none, so you get no account rather than a guess. These are automated labels for review (judgments.automated_decision: false), never a statement of who runs an account.
• When a seed's lookup on a platform was missing a part (the judge or the check was unavailable, or one of its searches failed), that platform may list fewer accounts for the seed or none, and data.platforms.<platform>.error_codes and the leg on the legs route name why: judge_unavailable, verification_unavailable or search_partially_failed. Such an answer is never cached, so the same request sent again with new_run=true tries those lookups again.
• Each lookup is a search of the run, billed at find-accounts' own price (for example 2 credits on Instagram, TikTok or X for a name, 16 on LinkedIn for a company with its domain). A lookup keeps that price when no account matches, because the searches and the judging ran; a part that fails or could not be judged is refunded. The estimate and dry_run price every one, and a call holds at most 36 of them, so 12 seeds on 3 platforms answer in the call and more continue in the background. A resume never looks a seed up twice. Nothing else is judged or billed unless you ask for label, include=contacts or a filter that needs a profile.
• seeds with keywords, query, brands, groups, hashtags or another subject, with a preset, or with a view other than accounts is a free 400 naming both fields.

{
  "account": { "key": "instagram:…", "platform": "instagram", "username": "example.creator" },
  "match": {
    "seed": "Example Creator", "level": "same", "confidence": 0.94, "match_confidence": 0.9, "basis": "judged",
    "evidence": { "website_match": false, "cross_link": false, "bio_consistent": true, "fan_or_parody": false, "domain": null, "domain_match": null, "domain_source": null }
  },
  "matches": [{ "seed": "Example Creator", "level": "same", "match_confidence": 0.9, "basis": "judged" }]
}

Listings and places near a place

near is the place the listings, places and web searches look in (a web search sends a place name as its location): a place name (near=Dubai) or lat,lng (near=25.2,55.27). It does not filter other rows; a request where no search reads it says so in _warnings, and so does a place name that names several places, or none (which one was searched, or that nothing was).

search_in=listings searches marketplaces by keyword: Facebook Marketplace around near, and the marketplaces named in platforms (ebay, amazon, aliexpress, gumtree, tiktokshop, walmart, each searched only for listings). Each row is record_type: listing with price { current, currency }; where the marketplace rates the product, its stars and its number of ratings are in rating { value, max, count }, and engagement.comments on a listing row is that same number of ratings.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "query=rolex" \
  --data-urlencode "platforms=facebook,aliexpress,walmart" \
  --data-urlencode "search_in=listings" \
  --data-urlencode "near=Dubai" \
  --data-urlencode "max_credits=20"

{
  "id": "as_wrxfc6057q4b", "platform": "amazon", "record_type": "listing",
  "url": "https://www.amazon.com/dp/B0HJ2ZVRNZ", "published_at": null,
  "text": "Rolex Pre-Loved Oyster Perpetual Explorer II Automatic Watch 40",
  "price": { "current": 11690, "currency": "USD" }, "author": null,
  "judgments": { "relevance": { "p": 0.71 } }, "matched_keywords": ["rolex"],
  "provenance": { "endpoint": "/v1/amazon/product-search", "request_id": "req-…", "captured_at": "2026-10-18T10:24:58.829Z" }
}

• Facebook Marketplace needs near: without it the request is a free 400 naming near. A place name is looked up first (1 credit), then searched at its coordinates; its listings are dated, carry the place they are listed in as geo.place, and are walked newest first when you send a window.
• Where a marketplace's rows name their seller (AliExpress, TikTok Shop and Walmart), the seller is the row's author, keyed by the marketplace's seller id, and rolls up as an account under view=accounts. Facebook Marketplace search rows name no seller, so under view=accounts each kept Marketplace listing is looked up once on marketplace/item (1 credit a listing, in credits.by_stage.enrich and priced by dry_run), and its seller becomes the row's author, keyed by the seller's profile URL, and rolls up as an account. eBay, Amazon and Gumtree search rows name no seller. A seller is linked to an Instagram account only when its listing links that profile, never by a matching name.
• Listings are checked against your keywords alone, free, even when you send a context: a listing for sale never reads as an opinion or an experience, so the context check would drop real listings.
• Each marketplace searches its own markets from country (eBay 19, Amazon 13, TikTok Shop 16, Walmart US and CA, Gumtree GB, AliExpress any). A country a marketplace does not serve is named in _warnings and not searched there. Etsy has no keyword search, so it is not a listings source.

search_in=places searches places at near: the businesses a keyword names there (record_type: place, with the name, category and address in text and geo.place, its stars and its number of reviews in rating { value, max, count }; on a place row engagement.comments is that same number of reviews, not comments), and, when instagram is among the platforms, the posts at the Instagram places named for near.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "keywords=dentist" \
  --data-urlencode "search_in=places" \
  --data-urlencode "near=Lisbon" \
  --data-urlencode "max_credits=10"

{
  "id": "gq_xprk95xfx015", "platform": "google", "record_type": "place", "published_at": null,
  "text": "Impress Porto\n\nOrtodontista\nR. de Sá da Bandeira 676, 4000-431 Porto",
  "rating": { "value": 4.9, "max": 5, "count": 2824 }, "engagement": { "comments": 2824 },
  "geo": {
    "country": { "value": "PT", "source": "post_geotag", "confidence": 0.9 },
    "place": { "name": "Impress Porto", "country": "PT", "source": "post_geotag", "lat": 41.1520273, "lng": -8.6059457, "address": "R. de Sá da Bandeira 676, 4000-431 Porto", "category": "Ortodontista" }
  },
  "judgments": { "relevance": null }, "matched_keywords": ["orthodontist"],
  "provenance": { "endpoint": "/v1/google/business/search", "request_id": "req-…", "captured_at": "2026-10-18T10:30:30.378Z" }
}

• A places search needs near. Instagram finds its places by name, so with Instagram near must be a place name.
• Businesses are kept without a relevance check, so a context never drops them and nothing is charged for one; a label you ask for still judges them, and the posts at an Instagram place are judged like any post. summary.record_types.place counts them.
• Instagram's places named for near are checked for being there (a condo in Florida named after Aruba is not walked; 1 credit per 25 checked), and the posts at up to three of them are walked newest first back to since. Each post carries its place as geo.place and its country from it. A busy place fills a page in about a day, so a month in the past is reached through quieter places or a background run; data.platforms.instagram.window says how far each walk reached, and when Instagram's later pages fail upstream a _warnings line says how many walks stopped at page 1 and that a resume with retry_failed=true reads further.
• Prices are the lanes' own: a place search 5 credits for up to 20 businesses, an Instagram place search 5, and 5 a page of about 60 posts at a place. The estimate and dry_run price every page a walk may take.

Search interest per group

include=interest adds data.interest: how much people searched for each of a group's keywords over time, beside the rows. Every group reads Google Trends in its market: its first country, or the United States when it has none, because Google Trends here has no worldwide reading (each series names its market in geo). A group whose market is KR or whose sources include naver also reads Naver's search trend.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "keywords=다한증,액취증,제모,미라드라이" \
  --data-urlencode "country=KR" \
  --data-urlencode "platforms=naver,youtube" \
  --data-urlencode "include=interest" \
  --data-urlencode "period=90d" \
  --data-urlencode "max_credits=60"

{
  "window": { "since": "2025-10-18", "until": "2026-10-17", "widened": true, "google_trends_timeframe": "past_12_months", "google_trends_reaches_since": true, "naver_time_unit": "week" },
  "series": [
    {
      "group": "skin", "keyword": "다한증", "source": "naver", "geo": "KR",
      "scale_id": "naver:skin", "anchor": null,
      "points": [{ "date": "2025-10-13", "value": 32.2532 }, { "date": "2026-10-05", "value": 25.29012 }, { "date": "2026-10-12", "value": 19.02034 }],
      "partial_last_bucket": true
    },
    {
      "group": "all8", "keyword": "다한증", "source": "naver", "geo": "KR",
      "scale_id": "naver:all8", "anchor": "척추관협착증",
      "points": [{ "date": "2025-10-13", "value": 4.1648 }, { "date": "2026-10-05", "value": 3.26567 }, { "date": "2026-10-12", "value": 2.45606 }],
      "partial_last_bucket": true
    }
  ],
  "calls": { "planned": 8, "answered": 8, "failed": 0, "pending": 0 }
}

The second series is from a group of 8 keywords, which takes two calls per source. The second call repeats the group's first keyword (척추관협착증) as its anchor, so all 8 Naver series of that group share one scale_id.

• data.interest.series[] holds one series per group, keyword and source: group, keyword, source (naver or google_trends), geo, scale_id, anchor, points[{ date, value }] and partial_last_bucket. data.interest.calls counts the calls planned, answered, failed and not run yet, and data.interest.window names the dates read.
• A value is relative, not a count of searches: each source scales a call so that its busiest series peaks at 100. A week Google Trends left out is null, never 0. When partial_last_bucket is true, the last week or month is still being counted, so read it as incomplete rather than as a fall.
• Only series with the same scale_id can be compared. One call carries at most 5 series, so a group with more keywords takes more calls, and each call is scaled to its own peak: the same level reads 20 in one call and 80 in another, so values from two calls say nothing about each other on their own. Every call after a group's first therefore repeats the group's first keyword as its anchor, and discover multiplies that call's values by the anchor's level in the first call over its level in this one, which puts all of the group's series from one source on one scale. Put the keyword people search most first: an anchor that is searched rarely makes the join coarse, and an anchor with no interest in a call cannot join it, so that call's series keep their own scale_id, anchor: null and a _warnings line. Series of two groups, or of two sources, are never on one scale.
• A seasonal shape needs a year, so the series read at least 12 months: a shorter window is widened back to 12 months before its end, with a _warnings line, while the rows keep the window you asked for. Naver reads the exact dates, weekly up to two years and monthly beyond. Google Trends reads the shortest of its fixed ranges that reaches back to the first day (past_12_months for a window ending today, past_5_years for an older one), so its series can run past the window's end. Google Trends reaches back five years at most: a window that ended before then reads no Google Trends series and is not billed for one, with a _warnings line. A week still being counted is left out when calls are joined, so a call made later in the week does not shift the join.
• The calls are part of the run: they count in the call's budget of 36 searches (planned once per group, never per page), in max_credits and in the estimate, and dry_run lists each call in its plan with the keywords it sends and its price. A background run reads them once its searches are done, and a replay or a run read returns the stored series free.

When you want only the series, with no rows, call the search-interest endpoints directly instead: /v1/naver/search-trend with groups (up to 5 keyword groups on one scale, | between groups), start_date, end_date and time_unit, and /v1/google_trends/explore with keywords (up to 5), location and timeframe, at 5 credits a call. A discover run always pays for its row searches as well, so use include=interest when you want the rows and the series together. A dry run with include=interest says so in _warnings when its row searches cost more than its interest calls. For more than 5 keywords, repeat your most-searched keyword in every call and scale each call by that keyword's level, as the anchor join above does.

curl -G "https://www.socialcrawl.dev/v1/naver/search-trend" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "groups=다한증|액취증|제모|미라드라이" \
  --data-urlencode "start_date=2025-10-18" \
  --data-urlencode "end_date=2026-10-17" \
  --data-urlencode "time_unit=week"

curl -G "https://www.socialcrawl.dev/v1/google_trends/explore" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "keywords=다한증,액취증,제모,미라드라이" \
  --data-urlencode "location=KR" \
  --data-urlencode "timeframe=past_12_months"

Messages inside Telegram channels

Telegram has no public search across all its messages. platforms=telegram searches Telegram's public channels by keyword, on every view, and returns the channels themselves (2 credits a keyword). Add search_in.telegram=messages to read the messages too: discover then searches inside the first 5 channels that channel search finds, in its order, for messages that contain every word of the keyword.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "keywords=cheap watches" \
  --data-urlencode "platforms=telegram" \
  --data-urlencode "search_in.telegram=messages"

• Each message is a post row (record_type: post) dated by Telegram, filtered by your window and judged like every other row.
• A keyword costs up to 7 credits on Telegram: 2 for the channel search and 1 for each channel searched. A channel with no matching message costs nothing.
• Telegram returns only the newest matching messages in each channel (about 20), so a window older than those is reported as not reached.
• A message counts only when it contains the words as written: Telegram's own search also matches other forms of a word (watch for watches), and those messages are left out.
• With search_in.telegram=messages,accounts, the one channel search also gives the channels as accounts, so it is paid once.
• To search one channel you already know, call /v1/telegram/profile/posts with handle and q.

Communities about a topic: view=communities

view=communities answers the subreddits, Facebook groups, Telegram channels and YouTube channels where a topic lives, instead of the posts. Each platform's own community search finds communities by their name and description, and every Reddit post the run keeps adds its subreddit (a Facebook post in a group adds that group), so a community nobody named can come from the posts alone.

curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "keywords=dairy farming,cattle feed" \
  --data-urlencode "context=Indian dairy farmers discussing feed prices" \
  --data-urlencode "view=communities" \
  --data-urlencode "platforms=reddit,facebook,telegram" \
  --data-urlencode "languages=hi,en"

{
  "key": "youtube:channel:UC…", "platform": "youtube", "kind": "channel",
  "name": "Example Kombucha Channel", "url": "https://www.youtube.com/@example",
  "description": null, "members": 134000,
  "activity": { "posts_30d": null, "last_post_at": null },
  "judgments": { "fit": { "p": 0.96, "basis": "community" } },
  "evidence": [{ "id": "yt_…", "kind": "community_match", "relevance": 0.96, "matched_keywords": ["kombucha brewing"] }],
  "languages": [], "found_by": ["search"], "privacy": null
}

• Each community has key (<platform>:<kind>:<id>), platform, kind (subreddit, group or channel), name, url, description, members, activity { posts_30d, last_post_at }, judgments.fit, evidence, geo, languages, found_by (search, rows or both) and privacy (a Facebook group's label, else null).
• judgments.fit { p, basis } says how well the community fits your keywords and context. With basis: "community" the judge read the community itself: its name, its description and the post the search matched in it. A community found only through the posts kept in it, or whose own record had too little text to judge, has basis: "rows", the mean relevance of those posts. Under relevance=filter a community below relevance_threshold (default 0.5) is left out, and so is a community with no fit at all, so every community a filtered run returns has a fit; relevance=score and relevance=off keep a community the judge could not read, with fit: null.
• Communities rank by fit in steps of 0.1, then by members (a community whose platform publishes no count comes after the counted ones of its step), then by evidence. sort does not apply to this view.
• activity.posts_30d is the platform's own count where it publishes one (a Facebook group's posts in the last month), else null. activity.last_post_at is the newest dated post this run kept in the community, else null. Neither is ever estimated.
• evidence lists the search hit that found the community (community_match), then each kept post or comment in it (post, comment), by id.
• With no platforms, the run searches reddit, facebook, telegram, youtube. A platform with no communities in platforms is a free 400; a preset keeps its platforms that have communities. The community searches send no window, so period only narrows the posts that add subreddits and groups.
• Prices are the lanes' own: a Reddit community search 1 credit, a Facebook group search 1 credit plus 1 for each group it returns with its name, description, members and activity (up to 11), a Telegram channel search 2 credits plus 1 for each of up to 5 channels returned with its subscribers and description, a YouTube channel search 1 credit. The fit is judged as rows are: free against the keywords alone, 1 credit per started 15 communities against a context that differs from them. The roll-up into communities is free.
• The Facebook group search is a web search of public group pages, and most groups it finds are found through one post inside them, so it has no country of its own and country does not narrow it. For a topic tied to a place, many of the groups it returns are local groups elsewhere that one post mentioned; the fit drops them under relevance=filter, and their search and details are still billed. summary.by_platform.facebook.rows shows how many groups were collected and kept.
• summary.communities counts the communities by platform, kind and how they were found. pagination.next_cursor pages the rest, free. A background run may ask for view=posts,communities; its run route answers the posts, and ?view=communities (and results.jsonl?view=communities) its communities, rolled up from the stored rows on every read.
• A channel is also an account: a suppressed account never appears as a community, and if the suppression list cannot be read the call answers 503 rather than serve communities unfiltered.
• A Reddit user's own profile space (r/u_<name>) is a person, not a community, so it is never one. With author_identity=omit or hash, a Telegram or YouTube channel (which can be one person's account) loses its name, its URL and every mention of them in its description, and its key becomes null (omit) or the same stable hash the accounts view gives that account (hash); subreddits and groups are places and are shown as they are.

What a topic's posts are about: view=items

view=items answers the hashtags, mentions, sounds, topics and named things (apps, products, brands, companies, titles) that the kept rows of a run share, instead of the rows themselves. With comments=inline, each comment read under the top posts counts as a row of its own, so an item can come from comments alone.

curl -G "https://www.socialcrawl.dev/v1/prism/discover"   -H "x-api-key: YOUR_API_KEY"   --data-urlencode "keywords=best apps"   --data-urlencode "context=apps people recommend, use or ask about"   --data-urlencode "platforms=tiktok,youtube"   --data-urlencode "view=items"   --data-urlencode "comments=inline"   --data-urlencode "comments.per_post=100"   --data-urlencode "max_credits=40"

{
  "kind": "hashtag", "key": "hashtag:budgeting", "label": "#budgeting",
  "platforms": { "youtube": { "posts": 3, "distinct_authors": 3, "views_sum": 380600 } },
  "first_seen_at": "2024-01-11T22:54:45.000Z", "last_seen_at": "2025-09-14T13:46:32.000Z",
  "daily": [
    { "date": "2024-01-11", "posts": 1, "views": 24000 },
    { "date": "2024-11-24", "posts": 1, "views": 353000 },
    { "date": "2025-09-14", "posts": 1, "views": 3600 }
  ],
  "growth": { "ratio": null, "basis": "posts_second_half_over_first_half", "n": 3, "reason": "Growth needs at least 8 dated rows of this item in the pool; it has 3." },
  "country_share": null,
  "early_adopters": [{ "author": "youtube:UC…", "first_post_at": "2024-01-11T22:54:45.000Z" }],
  "top_posts": ["yt_mtwytm43p0g8", "yt_e4k18fz7rcmv", "yt_7zmwh3gaq6cx"],
  "origin": "pool", "platform_total": null, "rank": 1
}

• Each item has kind (hashtag, mention, sound, topic or entity), key, label, platforms.<platform> { posts, distinct_authors, views_sum }, first_seen_at and last_seen_at, daily[{ date, posts, views }] on the calendar of tz, growth, country_share, early_adopters[{ author, first_post_at }], top_posts (the ids of its best rows), origin and rank. Every count is over this run's kept rows: "first seen" means first in this run, never first on the platform.
• growth { ratio, basis, n } is the posts in the second half of the window over the first half, among this run's rows: it describes what the searches found, not the platform as a whole, and searches that read newest first sample recent days more densely. Under 8 dated rows it is withheld: ratio: null with a reason.
• view=items is a run's only view: sending it with another view (view=posts,items) is a free 400 naming view. Start a second run for the other view.
• An items run's route takes wait_s, changes_since, view, cursor and page_size (or limit); any other parameter (platform, group, sort, state) is a free 400 that names it, since items are rolled up across the whole run. Its results.jsonl streams the items, one per line, then {"complete":true}, and takes view and cursor.
• A sound is the post's own sound id (TikTok and Douyin), or Instagram's audio cluster where a row carries one, which groups different uploads of the same sound. Under author_identity=omit or hash, a sound whose title is the platform's "original sound" form (which carries its creator's handle or name) is labelled original sound, and its key still groups its uploads. A topic is the niche label already on the rows, so it appears with label=niche.
• An entity is chosen from the row's own words: a capitalised name, an app named by an App Store or Google Play link, a link's site or an @handle that the text itself contains. A judge picks at most one per row, or none, so an entity item only ever names something its rows say. Names that are one another's spelling ("Notion" and "Notion AI") are one item.
• Item rows render in format=compact (empty values dropped) and format=text (one line per item). summary.items counts the items by kind and origin and the rows judged for an entity. pagination.next_cursor pages the rest of the items, free.
• The entity choice costs 1 credit per started 25 rows judged (rows with no name in them are never sent), shown in credits.by_stage.items and, before the run, in dry_run's estimate.by_stage.items. Everything else about items is free. In a background run the entity choice runs once the rows are collected.

Trend boards with no keyword

view=items&country=DE (or mode=board) reads each platform's trend boards for the country: TikTok's local feed and hashtag board, YouTube's trending videos, Google's trending searches (under web) and Pinterest Trends. Each item names its board in origin (board:tiktok/hashtags/popular) and carries the board's own rank and count on board. A board item names its sound, hashtag or topic only: its early_adopters and top_posts are always empty, because the videos on a board are not rows of your run, and the creators and posts behind an item are listed only on the items found in your own posts (origin: "pool"). data.boards lists every board per country with its status: unsupported_country where the platform publishes no board for that country (TikTok's hashtag board covers 27 markets, Pinterest Trends 23; Instagram and YouTube Shorts trends have no country at all), unavailable where the platform has withdrawn the board. X and Reddit publish no trend board per country. Several countries can be read at once (country=ZA,NG,KE). Add keywords (mode=board&keywords=wedding) to get the boards and the items found in posts about the keywords together; mode=board reads items, so it needs no view, and a view other than items beside it is a free 400. Boards are read as of now and keep their own windows. A window (period, since, until) only picks the window of TikTok's hashtag board (7, 30 or 90 days, the narrowest that covers it) and of Google's trending searches (24 hours, 48 hours or 7 days). TikTok's local feed, YouTube's trending videos and Pinterest Trends are today's lists, and no board item is filtered by the dates. A board with no keywords that is sent a window says so in _warnings; on a board with keywords, the window narrows the posts. country must be an ISO 3166-1 alpha-2 code; any other code is a free 400 naming country, with did_you_mean where a common alias names one (UK is GB). Each board call is billed at its own price: TikTok's local feed 5 credits, its hashtag board 6, YouTube's trending videos 1, Google's trending searches 5 and Pinterest Trends 10, so Germany's five boards cost 27 credits.

Sites found for you: sites=auto

sites=auto (or search_in.web=discover_sites) finds the forums, blogs and article sites that hold your topic, so you do not have to name them. For each keyword and language, discover runs up to 4 searches on the web: the keyword alone, then the keyword with the words people use for a review, a forum and a question in that language (for example 후기, 커뮤니티 and 질문 in Korean, or 口コミ, 掲示板 and 知恵袋 in Japanese). Their results are rows of the run like any web row. The judge reads them, and discover ranks their sites by kept rows per credit, with half a credit added to each site's credits so that a site found once among twenty results never outranks one found several times, then searches the top sites_auto_max sites (default 5, at most 20) the way listed sites are searched. Sites discover already searches natively (YouTube, Reddit, Naver and the other platforms, the review sites and the marketplaces such as eBay, AliExpress, Gumtree, Walmart and Amazon), news publishers and sites that contain one of your exclude_terms are never chosen.

curl -G "https://www.socialcrawl.dev/v1/prism/discover"   -H "x-api-key: $SOCIALCRAWL_API_KEY"   --data-urlencode "keywords=excessive sweating treatment"   --data-urlencode "platforms=web"   --data-urlencode "sites=auto"   --data-urlencode "country=US"   --data-urlencode "period=365d"

[
  { "domain": "bonsaiempire.com", "rows_kept": 24, "bodies_asked": 0, "dated_share": 0, "discovered": true,
    "discovery": { "hits": 6, "kept": 5, "kept_share": 0.83, "kept_per_credit": 5.44, "credits": 0.92, "searched": true, "excluded": null } },
  { "domain": "reddit.com", "rows_kept": 6, "bodies_asked": 0, "dated_share": 0.5, "discovered": false,
    "discovery": { "hits": 6, "kept": 6, "kept_share": 1, "kept_per_credit": 10.75, "credits": 0.56, "searched": false, "excluded": "native_source" } }
]

• data.sites lists every site the search found, one entry per domain. Each has discovered and a discovery block with hits, kept, kept_share, kept_per_credit (the rate without the half credit), credits (the discovery credits shared out to the site), searched, and excluded (native_source, news, excluded_term or named, else null), beside its kept rows and what its bodies gave.
• search_in.web=walk also walks each named or found site: the site's map is filtered by the keyword, up to walk_urls pages per site and keyword (default 50, at most 500), and each page that no other search found is read once. The rows are judged before their pages are read, so an off-topic page costs nothing.
• The sites are chosen once, when the run starts, and stored with the run, so a resume never searches for them again. dry_run prices the searches of the sites to be found as conditional legs and the walk's pages in estimate.by_stage.bodies.
• A walk of more than 50 pages, or more found sites than one call can search, runs in the background.
• expand_from=suggestions (with expand from 1 to 3) plans the extra searches from what people type into the YouTube and TikTok search boxes for each keyword: both suggestion lists are read first, at 1 credit each per keyword, and given to the planner. Without it (expand_from=keywords, the default) expand plans from your keywords alone, as before. expand_from without expand is a free 400.

How long does a call take?

Every platform search is a real call to that platform, so it takes seconds per platform call, and the searches run in parallel. A request that fits one call answers within deadline_s (40 seconds by default, 15 with depth=quick, at most 96). A background run of many keywords and pages takes minutes per run, and a very large one takes hours. Set your client timeout to deadline_s plus 10 seconds, so 50 seconds by default and 25 seconds with depth=quick.

Is a keyword an exact match?

No, and not a wildcard either. Each keyword is sent to every platform's own search, which matches words the way that platform does: most return posts containing the words or close variants, ranked by the platform. With expand=1 to 3, discover also plans extra searches from your keywords and context. Then every row is read by the judge against your keywords, or against context when you send one, so rows about something else are dropped under relevance=filter. literal_match on a row says whether a keyword appears in its text as written, and exclude_terms and contains filter on the text exactly.

One call or a background run?

A request answers in the call when it fits one call's budget: at most 6 keywords, at most 36 platform searches (pages to reach a past window, and Instagram's extra page after it switches search surface, included, and every search counted 1 + expand times), at most 3 pages_per_platform, at most 50 joined rows (include=author_country or instagram_views each join up to limit rows per group, and include=body page reads count with the joins against those 50 extra calls), a limit within the call's cap, one view, and no depth=deep. A GET whose deadline_s is too short for its searches and the judging their rows need runs in the background too, or answers NEEDS_ASYNC with async=false. Anything larger continues in the background (async=auto, the default) and answers 202 with the run and empty data.items. Send async=true to always run in the background, or async=false to get NEEDS_ASYNC (422, free) instead of a 202. GET /v1/prism/discover?...&dry_run=true answers the plan of searches and the estimate of credits and seconds, free, and starts nothing. Its estimate.credits.expected is calibrated on measured runs (22/10/2026; view=accounts on its own fit of 25/10/2026), so it is what a run of that size usually spends, while credits.max is the most the run can spend; a run that reaches max_credits stops cleanly with the rows it has, with stopped_because: max_credits. Its data.suggested_max_credits is the max_credits to approve: the estimate's credits.max, the most the run can spend. A run is billed only for what it spends, so the unused part of the cap costs nothing. data.request is the request as the run will read it, typed (groups as objects, numbers as numbers); normalized_params keeps the GET's string form. A dry run's _warnings lists what the real call would warn about, then the estimate's own lines, as the 202 does.

Lists and groups too long for a URL go in the JSON body of POST /v1/prism/discover, which takes the same fields, requires max_credits unless dry_run is true, and always runs in the background. async=false on a POST is therefore refused as conflicting_params; async=true and async=auto change nothing. A body over 1 MB is a free 413.

A long author list

POST /v1/prism/discover/inputs with { "kind": "authors", "authors": ["nasa", "@natgeo", "twitter:spacex"] } stores 1 to 10,000 handles (each at most 100 characters) and answers 201 with author_list_id, which any run takes in place of authors. A bare handle matches on any platform and platform:handle on that platform only. A list is free, belongs to your account, and expires after 30 days; an account holds at most 20 at once, and a 21st is a free 400 input_limit. authors itself takes at most 100 handles on the GET and 1,000 on the POST.

With authors_match=walk, discover reads each listed author's own posts in the window (Instagram, TikTok, YouTube, X, Facebook, Threads, LinkedIn and Reddit) and keeps the ones about your keywords or context, judged like any search row. Name each author with its platform (x:handle, instagram:handle) or its profile URL; a LinkedIn author needs its profile or company URL. A bare handle is read on every platform of the request that has a feed. An author on a platform the request does not search is listed in _warnings. Each author costs one page of its platform's feed, or pages_per_platform pages, and dry_run shows the total; a list larger than the call's budget continues in the background. On the platforms it reads, walk replaces the keyword search. A platform of the request with no account feed, such as news in the default preset, searches nothing and costs nothing when every listed author names another platform, and _warnings names it. When the list holds a bare handle, or an author named on that platform, the platform still searches your keywords and keeps only rows by the listed authors. A request left with nothing to search is a free 400 naming authors.

Posts you already hold

exclude drops the rows you name, but in a URL it fits only a few hundred ids. To leave out every post you already hold, store them once: POST /v1/prism/discover/inputs with { "kind": "exclude", "exclude": ["rd_0123456789ab", "https://www.reddit.com/r/PersonalFinanceCanada/comments/1abcde/", "reddit:handle"] } stores 1 to 50,000 entries (each at most 200 characters, in a body under 4 MB) and answers 201 with exclude_list_id. Then send exclude_list_id on any GET or POST of /v1/prism/discover, from any API key of your account. Its entries join exclude: an evidence id drops that row, a post URL drops the row with that post, however the URL is written (www., a share link's tracking parameters), and an account key drops every row by that account. Dropped rows are never judged or billed; with include=dropped they carry drop_reason filter:exclude. Evidence ids are the shortest entries, so 50,000 of them fit in one body. A list cannot be changed once stored: to add posts, store a new list and send its id. An exclude list counts toward the same 20 lists as author lists, and expires 30 days after it was stored, or 31 days after the last run that read it, so a list a schedule uses stays live; an unknown or expired id, or one of another account, is a free 400 invalid_param naming exclude_list_id.

Run statuses

data.run.status is one vocabulary for every run:

data.next.resume_body is the JSON body to send with next.resume_url, ready to copy: {} by default, {"max_credits": N} when the run stopped at its cap, and {"retry_failed": true} when failed work can be sent again. It is null exactly when resume_url is. A run stopped at max_credits also carries data.run.suggested_max_credits, the total cap (counting what is already spent) that finishes it: the larger of the run's estimate credits.max and what is spent plus the most every unsent call can cost, and always above the cap it stopped at. Only what the run spends is billed, never the unused part of the cap.

stopped_because says why a run stopped: time, max_credits, key_budget, insufficient_credits, upstream_failures, service_unavailable, capacity, internal_error, cancelled or key_revoked. time belongs to a call with a deadline (the GET's deadline_s); a background run has no deadline, so when its searches keep waiting for a free slot it pauses with capacity instead. A partial run held up only by judging names time, service_unavailable or max_credits, and its waiting rows are marked judgment_status: "pending" and counted in data.run.legs.judging_pending. data.run.progress.rows_kept counts judged kept rows. data.run.legs counts the run's search calls by final status (done, empty, failed, skipped, pending); the fetches that follow a search (post bodies, joins, search-interest calls) are not searches, so a failed one does not show in legs.failed. data.run.calls counts every call the run made, those included, by the same statuses, and equals the rows of the legs route: the kind of a row there (also published as lane) tells a search from a page read, a join, a comment page or an interest call, and data.counts on that route holds the run's searches and calls. A call the run's own code did not send (out of time, at max_credits, no free slot, our own 429, a 402, our own outage) is stored pending, never failed, with why in its error_code (leg_deadline_passed, max_credits_reached, no_slot, rate_limited, idempotency_in_progress, insufficient_credits, key_budget, key_revoked or service_unavailable); failed means the platform answered with a failure.

A run paused with service_unavailable (an outage of ours) or capacity (its searches, page reads, joins, comment pages or account profile lookups waited for a slot or were left unsent: another run on the same key was using its share, or the platform was busy across accounts; a background run never stops for time) is resumed automatically about 2, 5, 15, 60, 60 and 60 minutes after each pause, at most 6 times per outage (a resume you send, or a step of the run that completes, starts the count again); after that its next_step asks you to resume it. A pause for insufficient_credits, key_budget or max_credits never resumes by itself, because it needs your decision. A paused run's next_step also says the date to resume before, when the run and its rows expire.

In the background a run searches up to 30 platform pages at once, and rows become readable as each background step of up to 50 seconds commits. A background run reads page bodies (include=body) and translates (translate_to) once per run, in a step of its own after its rows are judged and joined: the first body_limit rows it delivers get their page read, never more however many steps the run takes, so body_limit and the translation are spent once, as the estimate prices them. A page read cut short or not sent waits as pending for the next such step, and a resume sends it. An account runs ten background runs at once; an eleventh answers 202 with status: queued and starts by itself when one of the ten settles. Runs on one API key share that key's 30 searches in flight: while two runs on a key are active each gets an equal share (15 each), and a run alone on its key gets all 30. A POST, or a GET answered 202 for the background, sent while another run on the key is active says so in _warnings. Two large runs on one key therefore take about twice as long each as either would alone; run them in sequence, or on two keys of the account, when one should finish first.

How max_credits and your balance stop a run

Each step of a run reserves its price before it runs: a search reserves its lane's price, a profile lookup its own price, and a slice of judging what that slice can cost. A step that fits the room left under max_credits and your balance runs; the run pauses at the first step that does not fit, with max_credits or insufficient_credits in stopped_because, before that step is bought. A slice of account lookups is sized to what is left, so a run at 16 of max_credits=50 keeps buying lookups and their judging up to 50.

data.run.credits.spent is what your balance paid for the run, and it matches the run's rows on /v1/credits/transactions. When a step's charge is refused because the balance moved while it ran (another run or call spent it), that step's credits come off spent again and the run pauses insufficient_credits.

A view=accounts run that pauses keeps every account it has found readable. The default read lists the kept accounts it has judged; state=pending lists the accounts it looked up and has not judged yet, each with status.judgment: "pending", its profile and the posts that found it in evidence[]; state=all lists every state. The paused run's next_step says how many are pending. A resume after a top-up carries on from where the run stopped and never buys a lookup twice.

Never pay twice

An identical request while its run is queued, running or paused returns that run (deduplicated: true); a paused run comes back with a next_step naming resume. An identical request within 24 hours of a completed run returns its stored result, free. An identical GET within 24 hours of a partial GET returns that run free, with a next_step naming resume. "Identical" means the same subject, sources, window, filters, judging, views, depth, expansion, pages and data-changing include values. Fields that only shape the answer or the spend do not count: limit, limit_per_keyword, format, fields, author_identity, sort, sample, max_per_author, max_per_platform, max_credits, deadline_s, async, retention_days, fresh, cursor and page_size. A stored run is matched only when it was asked for at least as many rows: the same or a lower limit returns it free, and a higher limit starts a new, billed run. A higher max_credits alone still returns the stored run free; when that run is paused (or is a partial GET), its next_step says to resume it with the higher cap. A partial POST run is never matched. Send new_run=true to start a fresh run anyway.

Reading a run

Reading a run is free. Copy the URLs in data.next; never assemble them.

The run reads filter for free with group, tag.<key>=<value>, platform, keyword, state=kept, dropped or all, include=dropped and include_pending=true, and a settled run also takes sort; sort or order=rank on a running run is the free 400 order_rank_while_running. A key holds at most 5 waits (wait_s) at once, and a sixth answers at once as if wait_s=0, so wait on one run at a time. view must be the run's own view. Every read takes limit as the same setting as page_size (the run read and its accounts, creators, communities and items, the call log and the runs list); both at once must agree. A run route refuses a parameter it does not take with a free 400, and DELETE and resume take none. Every run-route 400 carries the same details: param (the field to change), fields (every field it names), allowed (the names or values it takes, when known), did_you_mean (the closest one, when one is close, so pagesize names page_size) and a next_step that names what to send. While a run is running its rows come in arrival order, so a cursor never skips a row; once it is settled, order=rank is the default. A cursor keeps the order and the filters it was issued with: one taken while the run was running keeps paging in arrival order after it completes, and sending it with other filters, or an order that contradicts it, is a free 400.

A resume of a queued or running run answers 200 and starts nothing; two resumes at the same moment start the run once. A resume of a completed run is 409 RUN_STATE_CONFLICT whose next_step names POST next.more_url, the way to get more from a completed run, except an accounts run whose full page left accounts no lookup reached, which next.resume_url offers and the resume looks up. A run paused at its cap and resumed without a higher max_credits is a free 400 whose next_step suggests a cap. A partial GET run resumes as a background run. A resume reaches every kind of work the run left: its searches first, then the rows still waiting for the judge, the joins not sent, the page reads and translation, the comment pages, and the settle, in that order. Only work that is not done runs again (with retry_failed, failed and skipped calls of every kind too): a finished search, page read, join or comment page is never fetched again, and no stored row is removed or gets a new id. A search whose platform cursor expired is walked again from its first page; those pages bill again, only rows not already stored are kept, and _warnings says so. A resume extends the run's expiry to at least today plus its retention_days. A resume also judges the kept rows that were not judged yet, and only those. A resume answers 202 with the run queued instead of running when your account already runs ten background runs; it starts when one of them ends. Searches of a failed GET that were refunded run again on resume and bill again; their earlier rows are never served free.

When extra searches (expand) cannot be planned in time for some keywords, those keywords run alone and the run settles partial with stopped_because: service_unavailable. _warnings (on the GET) and data.run.limits say so, and a resume with { "retry_failed": true } plans the extra searches for those keywords only; searches already fetched never run again.

Some failures repair themselves. On a background run, a platform skipped after repeated failures is tried once more 5 minutes later, and its skipped searches run if that try works. A 402 that arrives within about 60 seconds of a top-up, while the balance does cover the run, is retried once after 60 seconds instead of pausing the run. When a platform is unavailable at the source (out of quota or down), data.platforms.<platform>.status is unavailable and next_step names the platform and says a resume will fail until it returns. data.run.credits.pending_refund shows credits charged to searches whose background step died before it finished; the nightly reconciliation pays them back, usually within a day.

pagination.next_cursor on the GET pages the run's stored rows, free, from its first kept row, so the next pages include the rows the GET already delivered. When the run store could not be written, the answer carries _warnings: resume_unavailable and no cursor. Buying more from the platforms is never a cursor. On the answer of a GET that finished in the call, data.next.continue_url buys the next pages of the searches that reported more, with data.next.continue_estimate; a background run walks its pages_per_platform instead, and its answers and run reads carry continue_url: null. Each continue_url buys its pages once, and sending it again returns the stored run free with deduplicated: true. A continue_url works on any day for as long as its run is kept (retention_days, default 7), and is refused once the run has expired. The max_credits you send with a continue becomes the run's cap, so a run that spent 45 of 50, continued with max_credits=60, may spend 15 more. As offered, continue_url carries a max_credits large enough to buy every page it estimates; edit it down to spend less, and the continue then pauses at that cap without buying anything twice.

The summary

data.summary holds counts only, each under an object that names its base, read from the stored rows: kept, dropped by reason, inside and outside the window, undated, per group, keyword, platform and language, the funnel and credits_per_kept. Each group, keyword and platform slice also carries its search credits and its own credits_per_kept, so summary.by_platform.<platform>.credits_per_kept shows what a kept row cost on each platform once off-topic rows are dropped. A slice also splits its kept rows by the judgments you asked for: sentiment with label=mention, intent with intent or label=intent, and stance with label=stance, where summary.stance counts kept rows by stance with uncertain counted apart. A run with brand_handles or mentions_of adds record_types, which counts reactions apart from the brand's own posts, tagged posts and ads. A run with comments=inline adds summary.comments: the posts selected, the comments read and kept, the pages, the posts deferred or waiting, and their credits. Every summary carries as_of_version and stale. While a run is queued or running the summary is refreshed as it progresses, about every 10 seconds at most, so a read can return counts as of an earlier version than the page: then stale is true, as_of_version is below data.run.version, and data._warnings has a line starting summary_stale:. The counts of a stale summary agree with each other as of that version. A run of 50,000 rows or more read before its first summary exists answers summary: null with a summary_pending: warning. Once a run settles, its summary is exact (stale: false).

The request

Tier 1 fields are what most calls need. Tier 2 fields shape the rows. Tier 3 fields are for background runs and experts. Every field is strict: an unknown field, a contradiction, or a field from a later release is a free 400 that names the field to change.

Tier 1

Tier 2

Comments

comments=inline reads the comments under the top posts of each group. comments.top_posts (1 to 50, default 3) is how many posts are read, taken in turn from each platform you asked for and ranked by comment count, or by views where a platform reports no count. comments.per_post (1 to 200, default 20) is the most comments read from each post, and comments.select_by=views ranks every post by views. Each selected post row then carries comments { status, endpoint, items, total, truncated, fetched, pages }, where status is ok, empty, failed or deferred, and the comments themselves are the comments.items array. engagement.comments on the same row is the platform's own count of comments, not the comments read. methodology.comments says, for the run, which posts were read, how many comments each, where they are on the row and which of your platforms have no comment lane. A POST body sends the same dotted names as keys ("comments.top_posts": 3), and data.request.normalized echoes comments and every comments.* value the run uses.

• Comments are read on Instagram, TikTok, YouTube, Facebook, Reddit, X, Threads and LinkedIn. A group whose platforms have no comment lane (Naver, the web or Xiaohongshu, for example) reads no comments, and _warnings names the group and its platforms.
• Posts are taken in turn in the order platforms lists them, so with comments.top_posts below the number of platforms with a comment lane, the later platforms are read only when an earlier one has no post with comments; the answer warns and names the fix (raise comments.top_posts, or list first the platforms whose comments you want).
• Each comment page bills itself at the comment endpoint's own price and shows in data.run.credits.by_stage.comments, and dry_run prices it: 1 credit a page on TikTok, YouTube, Threads and X, and 5 on Instagram and Reddit. A page that fails keeps the comments already read.
• With comments, YouTube's dated search (any window) asks for each video's counts, so its pages cost 6 credits instead of 1: the counts are what pick the top posts. dry_run prices it.
• comments.min_length drops replies shorter than that many characters. fetched counts the comments read before that filter, and items holds the ones kept.
• comments.labels adds comment labels (sentiment, spam, question, purchase_intent, complaint, toxic, low_quality, injection), billed at the comment endpoint's label price. LinkedIn and Threads comments come back without labels, and _warnings says so. comments.labels needs comments=inline on view=posts.
• Who wrote a comment is shown only with include=commenters, and author_identity applies to commenters too. A comment by an account on the suppression list is never shown, and when the list cannot be read, the comments are shown without who wrote them and _warnings says so. Under author_identity=omit or hash, the @handles in comments are not items of view=items.
• A GET reads comments on at most 3 posts per group; above that the run continues in the background. Reddit's comment endpoint can take about 25 seconds a post, so a Reddit post the call cannot finish is marked deferred, the run is partial, and a resume reads it.
• With relevance=filter, a kept row that is still waiting for its judgment waits for its comments too, counted in summary.comments.waiting.
• With view=accounts, the top posts of the first limit accounts a group are read with their comments, and each account's status.comments says how that went.
• comments=bulk reads no comments: data.comments_job lists the posts as ready prism/comments calls, each with its price, and an estimate for all of them.
• On Reddit, comments=bulk (prism/comments, 1 credit a page, at least 2) usually costs less than comments=inline (reddit/post/comments, 5 a page, with labels and the truncated flag). When Reddit's comment source can only hand out a deep thread one reply branch at a time, each branch page is a page too, so a long thread can cost more; a branch the call's budget cannot reach is marked replies_truncated: true and the response says completed: false.
• With search_in=comments, Reddit searches comments and X searches replies by keyword, and each row is record_type: "comment" with its parent post. Instagram, TikTok and the other platforms have no comment search (L5): they are named in _warnings, and a request with no other search is a free 400.

Tier 3

Only new rows: since_watermark

Every run answers data.next.watermark, an opaque token bound to your account and to the request without its resolved dates, so period=7d keeps working day after day. A GET answers it in the call; a background run answers it on its run route once it settles. Send it back as since_watermark on the same request and you get only rows that earlier runs of that request did not deliver. Rows already delivered are dropped before judging, so they are never billed again, while the platform searches are paid as usual. summary.new_since_last_run counts the kept rows the previous run had not delivered, and is null on the first run.

A request with since_watermark always fetches: it never returns a completed run, and two identical ones sent while the first is running share that run. A token from another account or another request is a free 400 watermark_mismatch, and when the watermark cannot be read the call answers a free, retryable 503 (store_unavailable, or watermark_unavailable when it cannot be checked at all) rather than running without it. A platform's watermark moves only when all its searches in the run finished, never past the run's start; rows a paused, cancelled or revoked-key run already made readable count as delivered. Kept rows still waiting for the judge (on a partial run with judging left, or a run paused at max_credits) do not count, and their platform's watermark does not move, so the next run returns them once they are judged. Right after a background run settles, data.next.watermark can read null for a moment until the watermark is written; reading the run again a second later shows it. Ids delivered within 3 days of the watermark are remembered, so a late-indexed post still comes through once.

Look further on a finished run: more

A completed run can look further without starting over: POST /v1/prism/discover/runs/{run_id}/more continues the same run, under the same run_id, and never fetches a row twice.

• An empty body ({}) fetches the next page of every search that reported more pages; pages (1 to 10) takes that many.
• { "new_searches": true } plans new searches over the run's keywords. Steer them with feedback: accept lists rows like the ones you want, and reject lists rows or accounts you do not want. Use each row's id, or author.key for an account. A rejected account's rows are dropped from then on.
• max_credits raises the run's cap, counting what it already spent; each new search bills at its platform's price under it.

curl -X POST "https://www.socialcrawl.dev/v1/prism/discover/runs/run_abc123/more" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"new_searches": true, "feedback": {"reject": ["tiktok:7012345678901234567"]}}'

The answer is 202 with the run running again, data.more (what was added) and data.next.changes_url: read it with wait_s and you get only the rows this more added (changes_since at the version before it). When nothing reported more pages and you sent no new_searches, the answer is 200 with data.more.nothing_more, free. A run that is not completed answers 409 RUN_STATE_CONFLICT (run_not_completed): resume continues the others. Feedback ids that are not rows or accounts of this run are a free 400 naming them.

Schedules

Add schedule to a POST and the request runs again on its own:

{
  "brands": ["acme"],
  "platforms": ["reddit", "twitter", "news"],
  "period": "7d",
  "schedule": { "every": "1d", "max_credits_per_run": 50, "max_credits_per_month": 1200, "name": "Acme daily" }
}

• The first run starts at once (or at start_at, at most 90 days ahead), and the answer carries data.schedule beside data.run.
• Price a schedule before you create it: send the same POST with dry_run=1 on the URL or "dry_run": true in the body. It is free, creates nothing, ignores Idempotency-Key (so the real POST can send the same key), and its data.schedule adds the month's figures: slots_in_month (the runs this UTC calendar month holds on the schedule's grid, counted for the whole month even when the schedule starts later in it), credits_per_month (every run at its estimated maximum, so an upper bound), money_per_credit (amount in currency GBP; basis is active_pack for the pack you bought, or starter_list before you buy one), money_per_month, and recommended_max_credits_per_month (a monthly cap that lets every run of the longest month start, with each run at its estimated maximum and the last one at your max_credits_per_run, plus 10%; it is never below max_credits_per_run, which the real POST requires). next_step says how to set max_credits_per_month from them. For a budget in money, divide it by money_per_credit.amount.
• Each later run starts from the previous run's watermark (see Only new rows), so it delivers only rows not delivered before.
• max_credits_per_run caps each run and defaults to the request's max_credits. With neither, or with a cap below what one run is estimated to cost, the answer is a free 400 on schedule.max_credits_per_run with a suggested_value from the estimate; the same check runs for a schedule with start_at, as does the balance check. max_credits_per_month pauses the schedule when one more run could take this UTC month's spend past it: that slot is skipped (discover.run_skipped, reason max_credits_per_month) and the pause sends discover.run_failed. It resumes by itself the next month, unless you paused it yourself.
• A run fires only when the previous one has finished. If it is still running or paused, that slot is skipped and recorded (previous_running, previous_paused), as is a slot with too little balance or key budget for max_credits_per_run. Three skips in a row pause the schedule and say why. A late fire runs once, never once per missed slot.
• Sending the same scheduled request again from the same key never makes a second schedule: the answer is 200 with the existing schedule and deduplicated: true (differs names the caps or every you sent differently; change them with resume). Send an Idempotency-Key too, so a retry after a timeout replays the first answer.
• A schedule with authors or author_list_id needs schedule.purpose (business, brand or creator); a key holds at most 20 of them.
• Sending the same request with schedule again from the same key answers the schedule that already exists (200, data.deduplicated: true) and starts nothing; send Idempotency-Key to replay the first answer exactly (Idempotency). A skipped slot whose run was refused records the refusal's own reason (for example max_credits_below_estimate) and the schedule's next_step says how to fix it.

Manage schedules with GET /v1/prism/discover/schedules (yours, newest first), GET /v1/prism/discover/schedules/{schedule_id} (with its last 10 runs and this month's spend), POST .../pause, POST .../resume (optionally with new caps) and DELETE /v1/prism/discover/schedules/{schedule_id}; all free. GET /v1/prism/discover/runs?schedule_id= lists one schedule's runs. When a scheduled run settles with rows, its schedule sends discover.new_rows (or discover.new_accounts and discover.new_items for those views) with the count and the first 100 new ids, after the suppression list (the count can include rows suppressed past those first 100), and links.changes, the run read that returns exactly those rows with their text and judgments (changes_since set to the event's since_version, which is 0 on a run's first event); a skipped slot sends discover.run_skipped, and a failed run or a schedule that pauses itself sends discover.run_failed. A pause you send yourself sticks: the schedule stays paused, sends nothing, and starts no run until you resume it.

Events and webhooks

A background run tells you when it moves: discover.progress (every 10%), discover.accounts_ready, and one settle event, discover.completed, discover.partial, discover.paused or discover.failed. Schedules add the events above. Each event carries counts and ids only, never row text, and links to the run's routes. A run answered in the call sends nothing.

Read them two ways, both free:

• Push. Register your URL once with POST /v1/webhook-endpoints { "url": "https://example.com/hooks", "types": ["discover.*"] }. Every run on your account then posts its events there, signed with Standard Webhooks and retried until you answer 2xx. The answer shows the signing secret once. See Event webhooks for verifying, testing and rotating.
• Pull. GET /v1/events?types=discover.* reads the same events in order from a cursor, and wait_s holds the read open until one arrives. See Events.

There is no webhook field on discover itself: one registration covers every run (see What is not offered).

Canonical requests

A request that needs a later release answers a free 400 not_released naming the release in details.release; on the GET, details.suggested_url is the nearest request that works today.

Presets

To find creators or influencers to work with, use creator search (/v1/prism/creators) rather than view=accounts&preset=creators: it measures each creator from its recent posts, filters on views and engagement, and ranks them with their reasons.

The consumer set was chosen by measuring in-window, on-topic kept rows per credit on 16/10/2026: YouTube 5.4, Reddit comments 3.2, Reddit posts 2.4, TikTok 2.4, X 2.0, Threads 1.9, news 1.6 and Instagram 0.25, so Instagram is left out of the default.

How far back can each platform reach?

platforms takes tiktok, instagram, youtube, reddit, twitter (or x), threads, facebook, linkedin, pinterest, bluesky, hackernews, forums, quora, github, news, web, naver, xiaohongshu (or rednote) and douyin, and the marketplaces ebay, amazon, aliexpress, gumtree, tiktokshop and walmart, which are searched only for listings (see Listings and places near a place). Each platform's own search decides how far back a window can reach. data.platforms.<platform>.window reports what each search actually reached, with reached: false, rows_outside and stopped_because when it stopped before since. Pages walked only to reach a past window count in the call's budget and are priced in the estimate. data.platforms.<platform>.status is ok, degraded (some searches failed or were skipped), failed (every search failed), skipped (none ran: the platform's circuit was open or no slot was free), unavailable (unavailable at the source: out of quota or down) or unsupported_country (the platform does not serve the requested country).

What it costs

A POST /v1/prism/discover answers X-Credits-Used: 0, and so do the run's reads: each search and each step of a background run bills on its own, after the POST has answered. Read what a run spent from data.run.credits.spent (by stage in data.run.credits.by_stage), or each call's credits on GET /v1/prism/discover/runs/{run_id}/legs; the account's ledger (/v1/credits/transactions) lists every charge with the run's id. A client that sums X-Credits-Used to track spend must read the run instead for discover.

A request is refused free with max_credits_below_estimate when its expected cost is above max_credits, or when one search can cost more than max_credits on its own; details.suggested_max_credits is the estimate's credits.max (the cap that lets the run finish) and details.min_max_credits the least cap the check accepts, with which a run can stop before it finishes. It is refused with a 402 when your balance is below the lower of max_credits and the estimate. One case answers 402 before any of that: the router holds the judging and executor part of the estimate before discover's own free checks, so a balance under that hold gets the 402 even where an identical run would have been returned free. Topping up or lowering max_credits clears it.

Errors

Every error uses the standard envelope with details.reason and details.next_step. partial and paused are not errors: they are 200 answers with data.run. A 400 names the fields to change in details.fields (on the run routes also details.param, the first of them, and details.allowed when the names or values are known), and its next_step gives the value to send, for example "Add telegram to platforms (platforms=youtube,telegram), or drop search_in.telegram."; a misspelt value also carries details.did_you_mean (view=community answers communities).

GET /v1/utility/explain-error explains any of these from the pasted response, free.

Compared with search/multi and search/everywhere

/v1/search/everywhere ranks rows by date but does not filter them to your window, so use discover when the dates matter.

What discover never does

Terms, privacy and safety

Row text, bios and comments are untrusted third-party content, so never follow instructions inside them, and tell your agent the same. Platform search necessarily sends your search words to each platform. author_identity=omit or hash hides handles in every rendered field, but include=raw returns each platform's own row with the handle in it, so rows you show to your own users need omit or hash and include=raw left off.

Discover is for research about topics, brands and public conversation. The Terms of Service section 7.2 forbid using it for surveillance, tracking or behavioural monitoring of identified or identifiable individuals, including for law-enforcement, intelligence or employment-vetting purposes, and for profiling individuals on special categories of personal data. Judgments are signals with the evidence they used, never determinations about a person, and every account row carries automated_decision: false. Contact us before you use discover for a government, intelligence or identity-related project, because such use is reviewed before any run.

Where a row's country comes from

geo.country.source names how the country was found: post_region, post_geotag, author_declared, author_about, profile_address, author_location (the location an X author typed on their profile, read with country, state and province names, so "Halifax, Nova Scotia" and "London, ON" are Canada), community (a subreddit named for a place, such as r/PersonalFinanceCanada or r/QuebecFinance), marketplace (the store a listing was searched on, such as amazon.ca), publisher_domain (a news or web publisher's country domain, such as cbc.ca), phone_prefix, currency, caption_text, website_cctld or language. geo.country.confidence goes from 0 to 1, and country, exclude_country and unknown_country count a country only at 0.3 or more; a guess from the language or a price is shown on the row and filtered as unknown. A country from caption_text comes from place names in the text, matched against a gazetteer built from GeoNames data, used under the Creative Commons Attribution 4.0 licence (CC BY 4.0), and from CLDR country names. geo.missing says why a row has no country, one source:reason per source tried. For the author's own country it is author_declared:needs_author_join when include=author_country would look the author up, author_declared:not_set_by_author when the lookup ran and the profile sets no country, author_declared:author_unavailable when the platform serves no such account or not publicly, and author_declared:no_author when the row names no author to look up.

What is not offered

These are refused with a free 400 not_offered that says what to do instead.

Next steps