# Discover (/docs/prism/discover)

Search many platforms for a topic, keep a date window, judge every row and get one de-duplicated list of posts

`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](#the-accounts-behind-a-topic), and [Find accounts](/docs/prism/discover-accounts.md) 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.

| You want | Send |
| --- | --- |
| A brand and its competitors every month, with the comments under the top posts and each brand's own posts | One POST with a group per brand ([Monthly brand report](/docs/prism/discover-brand-report.md)) |
| Several topics and their hashtags every few hours, with only new posts each time | One scheduled POST with a group per topic and `#tag` keywords ([Track topics and hashtags](/docs/prism/discover-topics.md)) |
| The subreddits, groups and channels where a topic lives | `view=communities` ([Communities about a topic](#communities-about-a-topic-viewcommunities)) |
| The hashtags, sounds and named things a topic's posts share | `view=items` ([What a topic's posts are about](#what-a-topics-posts-are-about-viewitems)) |
| What is trending in a country, with no keyword | `view=items&country=DE` or `mode=board&country=DE` ([Trend boards with no keyword](#trend-boards-with-no-keyword)) |
| The own accounts of companies or people you name | `seeds` ([Names to accounts](#names-to-accounts-seeds)) |
| Messages inside Telegram channels | `platforms=telegram&search_in.telegram=messages` ([Messages inside Telegram channels](#messages-inside-telegram-channels)) |
| Marketplace listings, or businesses and posts at a place | `search_in=listings` or `search_in=places`, with `near` ([Listings and places near a place](#listings-and-places-near-a-place)) |
| Forums and blogs you do not know yet | `sites=auto` ([Sites found for you](#sites-found-for-you-sitesauto)) |
| How much people searched for your keywords over time | `include=interest` ([Search interest per group](#search-interest-per-group)) |
| What a list of accounts posted about a topic | `authors` with `authors_match=walk` ([A long author list](#a-long-author-list)) |
| More searches from what people type into YouTube and TikTok | `expand=1&expand_from=suggestions` ([Sites found for you](#sites-found-for-you-sitesauto)) |

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

```bash title="cURL"
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"
```

```json title="Response"
{
  "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.

```bash title="cURL"
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](/docs/prism/discover-brand-report.md) 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.

```bash title="cURL"
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:

```json title="An account row"
{
  "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](/docs/prism/discover-creators.md)).
- 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](/docs/prism/discover-creators.md) 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.

```bash title="cURL"
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>`.

```bash title="cURL"
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).

```bash title="cURL"
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:

| Entry | Resolved as |
|---|---|
| `notion.so` or `https://www.figma.com/` | a company with that domain, named from it (`Notion`, `Figma`) |
| `BMW Group:bmwgroup.com` | a company with that name and that domain (`Name:domain`; the domain may be a URL) |
| `Trevor Noah` | a name alone, searched as a person (a creator) |

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:

```json title="POST /v1/prism/discover"
{
  "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.

```json title="A resolved account row (a name alone on Instagram, trimmed)"
{
  "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.

```bash title="cURL"
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"
```

```json title="A listing row (from query=rolex&platforms=amazon&search_in=listings&country=US, trimmed)"
{
  "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`.

```bash title="cURL"
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"
```

```json title="A place row (from keywords=orthodontist&search_in=places&near=Porto, trimmed)"
{
  "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.

```bash title="cURL"
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"
```

```json title="data.interest (a POST with groups in KR, trimmed to 2 of 32 series and 3 of 53 weekly points each)"
{
  "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.

```bash title="cURL"
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.

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

```bash title="cURL"
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"
```

```json title="A community row (from keywords=kombucha brewing&view=communities&platforms=reddit,youtube, trimmed)"
{
  "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.

```bash title="cURL"
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"
```

```json title="An item row (from keywords=budgeting app&platforms=youtube&view=items, trimmed)"
{
  "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.

```bash title="cURL"
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"
```

```json title="Two entries of data.sites (from keywords=bonsai care&platforms=web&sites=auto&country=US, trimmed)"
[
  { "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`](/docs/errors.md#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:

| Status | Meaning | What to do |
| --- | --- | --- |
| `queued` | Waiting for a free slot: your account already runs ten background runs. It starts on its own. | Wait on `next.status_url`; never resubmit. |
| `running` | Collecting, judging or delivering. | Wait on `next.status_url`; read rows as they arrive. |
| `paused` | Stopped by `max_credits`, the key's credit limit, the balance, an outage of our own, or searches that waited for a free slot (`capacity`). | Relay `next_step` to the user, then POST `next.resume_url` with `next.resume_body`. A pause for our own outage or for `capacity` resumes by itself, usually within about an hour. |
| `partial` | Finished with something missing: a failed platform, failed page reads, joins or comment pages, unjudged rows, accounts not looked up in the call, work left at `max_credits`, the GET's deadline, or a revoked key (`key_revoked`). | Use the rows; POST `next.resume_url` with `next.resume_body` if the rest is needed. |
| `completed` | Finished. | Read every kept row at `next.results_url`, free; POST `next.more_url` for more. |
| `failed` | Nothing could be kept: the searches failed at the source, or our own service was unavailable. | Follow `next_step`: it says which, and POST `next.resume_url` with `next.resume_body` runs it again. |
| `cancelled` | Stopped by `DELETE`; the rows are kept. | POST `next.resume_url` with `next.resume_body` to continue. |

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

| Call | What it does |
| --- | --- |
| `GET /v1/prism/discover/runs` | Your runs from any of your keys, newest first (`status`, `kind`, `created_after`, `cursor`, `page_size` or `limit`, 1 to 100, default 20). Use it when you lost a `run_id`. |
| `GET /v1/prism/discover/runs/{run_id}?wait_s=25` | Status, progress and a page of rows (`page_size` or `limit`, 1 to 100, default 50). `wait_s` (up to 25) answers early on a status change, a finished stage or 10% more rows. |
| `GET /v1/prism/discover/runs/{run_id}?changes_since={version}` | Only rows added or changed since the `data.run.version` you hold. |
| `GET /v1/prism/discover/runs/{run_id}/results.jsonl` | Every row, one JSON object per line, streamed. The last line is `{"complete":true}`; when the export stops early (after about 45 seconds) it is `{"next_cursor":"…"}` instead, and `?cursor=` with that value and the same filters continues it. |
| `GET /v1/prism/discover/runs/{run_id}/legs` | Every call the run made, searches and the fetches after them, with its platform, `kind` (and `lane`, the same value), search text, page, status, `request_id`, credits and `error_code`, up to 500 a page (`page_size` or `limit`, default 100). `data.counts` holds the run's `searches` and `calls`; its status counts are `data.run.calls`. |
| `POST /v1/prism/discover/runs/{run_id}/resume` | Continues a `paused`, `partial`, `failed` or `cancelled` run from its stored work and answers `202`. Send `next.resume_body` as the body; it takes `{}` or `{ "max_credits": 200, "retry_failed": true }`, nothing else. Free. |
| `DELETE /v1/prism/discover/runs/{run_id}` | Cancels a run. Its rows stay readable and `resume` continues it. A run that already settled answers `409 RUN_STATE_CONFLICT`. |

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

| Field | Default | Meaning |
| --- | --- | --- |
| `keywords` | none | The searches, comma separated; each runs once on each platform. Up to 6 run in one call. |
| `query` | none | One search phrase, never split on commas. |
| `context` | the keywords | What kept rows must be about, 3 to 2,000 characters. A persona or a question goes here, never in `keywords`. |
| `brands` (alias `brand`) | none | Each brand is its own group, searched by its name and labelled with the `mention` judgment. |
| `platforms` or `preset` | `preset=consumer` (accounts: the account set) | The platforms, in order, or a named preset. |
| `period`, or `since` and `until` (aliases `from`, `to`) | none | `Nd` (1 to 365), `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`, `last_quarter`, `this_year`, `ytd`; or dates `YYYY-MM-DD`, inclusive. `tz` sets the calendar (default UTC). |
| `view` | `posts` | What the run returns: `posts`, `accounts` (the accounts behind the topic), `communities` (see Communities about a topic) or `items` (see What a topic's posts are about). |
| `limit` | 50 on the GET (quick 20), 500 on the POST; accounts 25 and 100 | Kept rows per group; at most 100 in one call, which answers at most 300 rows in total and pages the rest, and 5,000 in a background run. Accounts: at most 50 in one call and 1,000 in a background run. |
| `max_credits` | 50 on the GET | The most the run may spend. Required on the POST unless `dry_run` is true. |
| `depth` | `standard` | `quick` (at most 3 fast platforms, 15 seconds) or `deep` (background). |
| `dry_run` | `false` | The plan and the estimate, free. |

### Tier 2

| Field | Meaning |
| --- | --- |
| `country`, `exclude_country`, `unknown_country` | Where rows or authors are, on the row's `geo` object; `country` also picks the news edition, and a country of the Arab League plans searches in `en` and `ar` unless you send `languages`. A row whose country is unknown is kept unless you send `unknown_country=drop`; with `include=author_country`, rows waiting on that lookup are judged after it. When a group names one country, its TikTok and YouTube searches are made from that country and its Instagram reel searches from that market (one of the 11 below), as `<platform>.region` does; send that platform's `region` to choose another. A group with several countries searches from each platform's default location. The dry run's `plan` shows each search's `region`. |
| `languages` | Rows in these languages; searches are planned in them, and with `country` the news edition is searched once per language it is published in (`country=CA&languages=en,fr` runs an English and a French search, each billed as its own search, at most 4 per country; a language the edition does not carry is named in `_warnings`). Malay and Indonesian count as one language, so `ms` keeps rows labelled `id` and `id` keeps rows labelled `ms`; a row with no detected language is kept. |
| `min_views`, `min_likes`, `min_comments`, `min_followers`, `max_followers`, `verified`, `media_type`, `link_domains` | Row and author filters, applied by code before anything is judged. `media_type` is `video`, `image`, `carousel` or `text`. |
| `exclude_terms`, `contains` | Drop rows with a term; keep only rows containing a string or URL prefix (without `keywords`, `contains` is searched). |
| `undated`, `estimated_dates`, `outside_window`, `min_text_length` | How undated rows, estimated dates, rows outside the window and very short rows are handled. |
| `sites` | Domains to search inside on the `web` source, up to 20, or `auto` to find them (see Sites found for you). `web` is added when you send no `platforms` or `preset`; a platform list or preset without `web` is a free 400. Named sites are searched next to `web`'s own keyword search of the whole web, so rows from other domains come back too; send `search_in.web=sites` to search only inside the named sites. |
| `relevance`, `relevance_threshold` | `filter` (default), `score` or `off`; the threshold is 0 to 1, 0.5 by default. Under `filter` a row is kept when `judgments.relevance.p` is at the threshold or above, the row is about what your keywords mean (`sense: target`, which a row can be without repeating them, such as a question asked in other words), it is more than a passing mention (`depth` 1 or more) and it is not a spam template. In the POST body a group can send its own `relevance_threshold` (same bounds) to keep more or fewer of its rows than the request, for example 0.3 on a long tail of patient questions; a group without one takes the request's. A threshold changes no price: judging against keywords alone stays free. With `include=dropped`, a row dropped as `off_topic` keeps its `judgments.relevance`, so you can read the scores of what was cut. Under `filter`, a row with too little text to judge (under 15 characters, or none) is dropped with `drop_reason: empty` and is never billed for judging; `score` and `off` keep it with `judgments.relevance: null`. Rows kept without a relevance check (a brand's own posts, reviews, places) and the rows of a `view=accounts` run stay kept. Under `relevance=score` no row is dropped, so `relevance_threshold` does nothing on the posts view and `_warnings` says so; on `view=accounts` it stays the account fit floor. |
| `label`, `intent` | Judgments to add (`mention`, `intent`, `niche`, `sponsored_model`, `stance`, or `none`), each billed; `label=mention` needs `brands` (or a group `brand`). `intent` keeps rows of these intents (`switching`, `complaint`, `recommendation`, `question`, `purchase_intent`, `selling`) and adds the billed `intent` judgment. `label=stance` reads each post's title and body and publishes `judgments.stance` as `{ label, confidence }`, with `label` one of `positive`, `negative`, `neutral` or `no_opinion`. A post the judge is not sure of has `label: null` and counts as `uncertain` in `summary.stance`. The stance is toward the group's brand, else its keywords, else its context. It is billed like any other label: 1 credit per started 25 freshly judged posts. With `view=accounts`, `fit`, `role` and `account_kind` judge accounts (the default). |
| `role`, `account_kind`, `targets_country` | Accounts only: keep accounts of these roles (`seller`, `reseller`, `buyer`, `warner`, `reviewer`, `promoter`, `other`), kinds (`individual_creator`, `brand_or_business`, `media_or_publisher`, `fan_or_repost_page`, `cannot_tell`), or that target these countries; each adds its judgment, and `label=none` with any of them is a free 400. |
| `active_within_days` | Keep authors who posted within this many days. |
| `questions` | Up to 5 questions of your own, judged on every account or row ([below](#your-own-questions)). |
| `posts_per_account` | Accounts only: posts read per looked-up account, 12 by default (1 to 100); one call reads at most 12. When you send it, the recent posts of every looked-up account whose profile passes your country, follower and badge filters are read and returned in its `posts` array (each entry `{ "post": {…}, "computed": {…} }`), with `status.posts` saying how the read went, and the estimate prices the posts pages. Without it, posts are read only when activity is needed (`depth=deep`, `active_within_days`, `sort=recent` or `sort=engagement`), and returned only with `depth=deep` or `comments`. |
| `sponsored` | `keep` (default), `exclude` or `only` rows flagged or disclosed as sponsored. |
| `limit_per_keyword`, `sort`, `sample`, `max_per_author`, `max_per_platform` | How many rows per keyword, in which order (`relevance`, `recent`, `engagement`, `views` or `views_per_follower`; accounts `fit`, `followers`, `engagement` or `recent`), and a representative sample. `max_per_author` and `max_per_platform` cap the sample, so they need `sample=representative` (`sample=representative&max_per_platform=40`). |
| `include` | `author_country`, `body` (full text of the top kept articles, pages and threads, with `body_limit`: default 10, at most 50 on the GET and 5,000 on the POST; a page behind a block or challenge is retried on stronger tiers, which can bill up to 5 credits; pages are read only for web pages, news articles (Google News, Naver news and webkr), Reddit posts and named `sites`, so on other platforms it reads, and costs, nothing), `raw`, `instagram_views`, `dropped`, `commenters` (with `comments=inline`, [below](#comments)), `interest` (search interest per group, see Search interest per group), `authors` (on posts: looks up the author of each kept row and fills `author.followers`, the badge and `account_kind` where the search left them empty, at the profile lookup's price; the estimate prices a lookup for every judged row, so `max_credits` must cover it even though the run bills only the authors it looks up); with accounts, `authors`, `contacts` (opt-in, never on by default) and `audience` (a TikTok creator's follower aggregates, which describe the followers, never the author). |
| `comments`, `comments.top_posts`, `comments.per_post`, `comments.select_by`, `comments.min_length`, `comments.labels` | `inline` reads the comments under each group's top posts, and `bulk` hands those posts to `prism/comments` ([below](#comments)). |
| `format`, `fields` | `evidence` (default), `compact` or `text`; `fields` keeps only the keys you name. |
| `author_identity` | `full` (default), `omit` or `hash`. It hides handles in every rendered field; a link that names the author is removed, except that a TikTok link keeps working with the handle written as `_` and a Threads post link becomes its `https://www.threads.com/t/<code>` form. But `include=raw` returns each platform's own row unchanged, handle included: for rows you show to your own users, send `omit` or `hash` and leave `include=raw` off. |
| `translate_to` | Adds `text_translated` in this language. |
| `continue`, `since_watermark` | The token from `data.next.continue_url`; a watermark from an earlier run returns only newer rows. |

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

| Field | Meaning |
| --- | --- |
| `groups` | POST only: up to 100 groups, each with its own `id`, `keywords`, `context`, `brand`, `exclude_terms`, `platforms` or `preset`, `search_in`, `languages`, `country`, `sites`, `tags`, `pages_per_platform` and `relevance_threshold`. Rows carry their group and `group_tags`; accounts carry `group` and `also_in_groups`. |
| `authors`, `author_list_id`, `authors_match` | Keep only rows by these authors. `filter` (default) searches and keeps the listed authors' rows; `walk` reads each author's own posts in the window instead and keeps those about your subject. |
| `seeds`, `mode` | `seeds` resolves names to their own accounts and implies `mode=resolve` (see Names to accounts). `mode` is `search` (default), `resolve` or `board` (trend boards, see Trend boards with no keyword). |
| `hashtags`, `search_in` | Hashtag searches; lane kinds per platform (Reddit and X comments, Naver's corpora, web sites, `discover_sites` and `walk`, a brand's `owned` posts, Instagram `tagged` posts, `ads`, `reviews`, `listings`, `places`, `communities`, and Telegram `messages`). |
| `near` | The place the listings, places and web searches look in: a place name or `lat,lng` (see Listings and places near a place). |
| `sites_auto_max`, `walk_urls` | With `sites=auto`, the sites found that are searched (default 5, at most 20); with `search_in.web=walk`, the pages walked per site and keyword (default 50, at most 500). |
| `brand_handles`, `mentions_of` | A brand's own accounts, and the accounts whose mentions you want (see A brand's own accounts, tagged posts, ads and mentions). |
| `review_sites`, `g2.url` | With `search_in=reviews`: the review sites searched (default `trustpilot,google,tripadvisor,app_store,google_play`; also `yelp`, `amazon`, `g2`), and the G2 product page (see Reviews of a brand). |
| `expand` | 0 (default) to 3 extra searches planned per keyword in total (`true` counts as 1 and `false` as 0, in the JSON body and the query string), spread across `languages` when you send several: they go to the languages in turn, those other than the keyword's own first, so `expand=2&languages=en,es` on an English keyword plans one Spanish and one English search. `expand_from=suggestions` also plans them from the YouTube and TikTok search suggestions (see Sites found for you). |
| `pages_per_platform` | 1 (default) to 10; above 3 the run continues in the background. A group can send its own (same bounds) to walk its searches deeper or shallower than the request, for example 2 pages on a broad set of short terms and 5 on a long tail in the same run; a group without one takes the request's. |
| `retention_days` | 1 to 30 (default 7). After it, a finished run answers `RUN_EXPIRED` on every route; a queued, running or paused run can still be read and cancelled. |
| `deadline_s`, `async` | The GET's time budget (10 to 96 seconds), and whether it may continue in the background. |
| `fresh`, `new_run`, `exclude` | Skip cached search pages at full price, start a new run, and leave out what you already hold: evidence ids, post URLs or account keys, up to 1,000. |
| `exclude_list_id` | A list of up to 50,000 evidence ids, post URLs or account keys stored with `POST /v1/prism/discover/inputs` (see Posts you already hold). Its rows are dropped with `exclude`, before judging and billing. |
| `<platform>.<param>` | A platform search's own parameter, such as `instagram.surface=relevance`. `tiktok.region` and `youtube.region` choose where the search is made from and do not limit results to that country; TikTok rows carry the video's country, so `country=` filters them. A group with one `country` sends it as these regions by default (see `country`), and a `region` you send wins. `instagram.region` (`ES`, `MX`, `DE`, `BR`, `KR`, `FR`, `ZA`, `NG`, `KE`, `AE` or `SA`) localises every Instagram reel search of the run the way [`region`](/platforms/instagram/search-reels) does on the reel search itself, and each search keeps its price; the hashtag searches are not changed. |
| `cursor`, `page_size` | GET only: `pagination.next_cursor` of an earlier answer pages that run's stored rows, free, `page_size` (1 to 100, default 50) at a time. |
| `schedule` | POST only: run this request again every `1h`, `6h`, `12h`, `1d`, `7d` or `30d`, each run from where the previous one stopped (see Schedules). |

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

```bash
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:

```json
{
  "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](/docs/idempotency.md)). 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](https://www.standardwebhooks.com) and retried until you answer `2xx`. The answer shows the signing secret once. See [Event webhooks](/docs/webhook-endpoints.md) 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](/docs/events.md).

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

## Canonical requests

| # | Request | Available |
| --- | --- | --- |
| 1 | Brand reaction for a month: `brands=aruba,curacao,bonaire&preset=travel&period=last_month&tz=America/New_York&exclude_terms=networks&max_credits=150` | Today |
| 2 | A chat agent's persona question: `query=electric cars&context=What do women over 50 say about owning an electric car?&depth=quick&period=90d` | Today |
| 3 | Sellers behind a topic: `keywords=replica rolex dubai,fake watches uae&context=accounts selling counterfeit luxury watches in the UAE&view=accounts&role=seller,reseller&targets_country=AE&period=90d&max_credits=400` | Today |
| 4 | Creators in a country: `query=recetas veganas&view=accounts&preset=creators&country=ES&min_followers=50000&verified=true&include=contacts&relevance=off&label=none&max_credits=100` | Today |
| 5 | Trends with no keyword: `view=items&country=DE&period=14d` | Today |
| 6 | Communities: `keywords=dairy farming,cattle feed&context=Indian dairy farmers discussing feed prices&view=communities&platforms=reddit,facebook,telegram&languages=hi,en` | Today |
| 7 | Links or referral codes: `contains=claude.ai/referral/&platforms=twitter,reddit,threads,github,web&relevance=off&period=7d`, then the same with `since_watermark` on every later run | Today |
| 8 | Market research for a client: a POST with one group per topic and market, tagged, with `include=dropped` and `body` | Today, in the [research guide](/docs/prism/discover-research.md) |

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

| Preset | Platforms, in order | Use it when |
| --- | --- | --- |
| `consumer` | youtube, reddit (posts and comments), tiktok, twitter, threads, news | What people say about a topic, product or brand (the default). |
| `b2b` | linkedin, reddit, news, web, twitter, hackernews | Business and professional topics. |
| `travel` | instagram, tiktok, youtube, reddit, pinterest, news | Destinations, hotels and trips. |
| `apps` | reddit, tiktok, youtube, twitter, news | Reactions to an app or a software product. |
| `news` | news, web, reddit, twitter, hackernews | Coverage and discussion of an event or a company. |
| `commerce` | tiktok, instagram, youtube, reddit, pinterest | Products and shopping. |
| `creators` | tiktok, instagram, youtube | Short-video and creator platforms only. |
| `korea` | naver, youtube, tiktok, instagram, threads, news, web | Korean-language research. |

To find creators or influencers to work with, use [creator search](/docs/prism/creators.md) (`/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).

| Platform | Price per search page | How the window is applied | Reach |
| --- | --- | --- | --- |
| TikTok | 1 credit | The narrowest date bucket covering `since`, newest first; when page 1 is entirely after `until` it switches to the relevance bucket and filters locally. | A date page covers about 2 to 3 days, so a window closed up to about a week back is reached directly; up to 180 days through the relevance bucket. Older than 180 days is not reached. |
| Instagram | 1 credit (hashtags 5) | Inside 90 days the relevance surface first, switching to the date surface when page 1 holds under 15% in the window; beyond 90 days the date surface. `instagram.surface=relevance` never switches. | 365 days at about 9 reels a page on the date surface. Views are empty on the date surface; `include=instagram_views` restores them. |
| YouTube | 1 credit (6 with a window and `comments`) | Exact dates. | Any window. |
| Reddit | 1 credit | The narrowest time bucket that misses at most 2 days, with pages. | Any window, with pages. |
| X | 1 credit | Exact dates, newest first. | Any window, with pages. |
| Facebook, Threads | 1 credit | Exact dates. | Any window. |
| LinkedIn | 5 credits (hashtags 10) | Date order with pages; switches to relevance when page 1 is after `until`. | A page of 10 posts covers under a day for a busy keyword, so keyword search reaches only the last few days. |
| Pinterest | 1 credit | Pages filtered locally. | Rows of any age arrive in relevance order, so pages add in-window rows at a steady low rate. |
| Hacker News, news | 1 credit | Exact dates. | Any window; news returns at most 100 rows a call. |
| Bluesky, GitHub | 1 credit | Pages filtered locally. | Rows of any date the search returns; only dated rows count in the window. |
| Quora | 5 credits | Pages filtered locally. | Rows of any date the search returns; only dated rows count in the window. |
| Forums | 10 credits | One fused search across forums, filtered locally. | Rows of any date the search returns; only dated rows count in the window. |
| Web | 2 credits per 10 results | Exact or bucketed dates from the group's market; only dated rows count in the window. | Any window, where the page publishes a date. |
| Naver blog, news, KnowledgeiN, cafe | 1 credit | The best 100 rows by relevance, then one newest-first page with a window. | By default, with a window, the top 100 plus one newest-first page; with `pages_per_platform=10`, up to the newest 1,000 rows per search. On a common word that is days, so narrower keywords reach further. Cafe rows are undated. |
| Xiaohongshu (`rednote`), Douyin | 5 credits per row returned | The narrowest `published` bucket covering `since` (`half_year` for 8 to 180 days, `all` beyond), filtered locally. | 180 days on `half_year`, older rows through `all`. The bucket is sampled by relevance, so part of it falls outside a shorter window: on 17/10/2026, 2 of 5 rows of each `half_year` sample fell inside a 90-day window. Rows outside the window are dropped as `out_of_window`. Neither platform publishes view counts. |

## What it costs

| Item | Price |
| --- | --- |
| A platform search | The platform's own page price (table above), only when it returns rows. A search that fails, finds nothing or is served from cache costs 0. |
| Relevance against your keywords | Free. Judging is counted per group and on fresh rows only: a verdict already in the cache costs nothing. |
| Relevance against a `context` that differs from the keywords | 1 credit per started 15 judged rows. A dry run adds a warning when this is the largest part of the estimate; judging against the keywords is free. |
| Each `label` value, and `questions` on rows | 1 credit per started 25 judged rows, each. |
| Account judging (`view=accounts`) | 1 credit per started 5 accounts per pass: the account judgments are one pass and your `questions` a second. When a call finds more accounts than `limit`, the accounts it looks up are judged again with their profile, at the same price for those accounts only. `label=none` without questions costs nothing. |
| Account lookups (`view=accounts`) | The profile lookup's own price per account (1 credit, 5 on LinkedIn), plus the posts pages read when activity is needed or `posts_per_account` is sent, for the accounts whose profile passes your country, follower and badge filters only; at most 50 accounts in one call. A lookup that finds nothing costs 0. |
| Account searches (`search_in` kind `accounts`) | The platform's own account search price per call; LinkedIn's (10 credits a call) runs only when `search_in.linkedin=accounts` names it. |
| A topic card (a `context` over 200 characters) | 1 credit. |
| `translate_to` | 1 credit per started 1,000 translated characters. |
| `sites` | Per site and keyword, page 1 is two searches: a site search of up to 10 results (1 credit) and one search of a second web index limited to the site, shown as `/v1/web/search (second index)` in the legs list and in row provenance (1 credit for up to 20 results; it is not the public `/v1/web/search` price). Each further page (`pages_per_platform` above 1) is one more site search at 1 credit. Without `search_in.web=sites`, each keyword also runs `web`'s own whole-web search at its page price. |
| `sites=auto` | Per keyword and language, up to 4 searches on each of the two web indexes (1 credit each), then the found sites' searches at the `sites` price. The ranking is free; judging the found rows against your keywords is free, and against a `context` it is priced as for any row. |
| `search_in.web=walk` | 1 credit per map of a site and keyword, then each page read at the page read's own price (login walls, blocks, challenges and empty pages cost 0). |
| `expand_from=suggestions` | Each keyword's YouTube and TikTok search suggestions, 1 credit each, read before the extra searches are planned. `expand` alone reads none and costs what it did. |
| Xiaohongshu and Douyin searches | 5 credits per row returned. Each search asks for `limit_per_keyword` rows (10 when unset, at most 20 a search on Xiaohongshu and 25 on Douyin) and is billed only for the rows it delivers. A GET collects at most 20 of their rows per group; more is refused free with a 400 whose `details.suggested_url` is the same request as a background run (`async=true`). `dry_run` shows the rows and their price per group in `estimate.per_row`. |
| `include=body` | The page read's own price per body. Login walls, blocks, challenges and empty pages cost 0; paywall previews, consent walls and pages that turn out to be lists are billed as served. Only web pages, news articles, Reddit posts and named `sites` are read, so a request with none of them prices and reads nothing. |
| `include=instagram_views`, `include=author_country` | One call per kept row (or author) at that endpoint's own price, shown in `estimate.by_stage.joins`: at most 50 joins in all on a GET, and every kept row in a background run. A lookup that finds nothing to add (a profile that sets no country, a reel with no view count) is refunded, so it costs nothing. |
| Listings (`search_in=listings`) | Each marketplace's own page price: Facebook Marketplace 1 credit (plus 1 credit for looking up a place-name `near`), eBay 5, Amazon 1, AliExpress 5, Gumtree 5, TikTok Shop 1, Walmart 5. A search that finds nothing costs 0. |
| Places (`search_in=places`) | A place search 5 credits for up to 20 businesses per keyword; with Instagram, its place search 5, the check of its places 1 credit per started 25, and 5 a page of about 60 posts at each of up to 3 places walked. `dry_run` prices every page a walk may take. |
| Reviews (`search_in=reviews`) | Per site and search, the lookup's own price (Trustpilot, Tripadvisor, Yelp and Amazon 1 credit; Google, App Store and Google Play 5), then each review page's own price (Tripadvisor 1 credit, the other sites 5) for up to 3 entities that fit. Judging the looked-up results costs 1 credit per started 25 results, so 1 credit per site and search. `dry_run` shows it in `estimate.by_stage.entity_resolution`, and its `plan` lists each lookup with the reviews it may read. |
| `include=interest` | 5 credits per call, one call per 5 series per source and group (a group of 8 keywords in Korea takes 2 Naver calls and 2 Google Trends calls, 20 credits). A call with no interest at all costs 0. `dry_run` shows them in `estimate.by_stage.interest`. |
| Trend boards (`mode=board`, or `view=items` with `country` and no keywords) | Each board call at its own price, per country: TikTok's local feed 5 credits, its hashtag board 6, YouTube's trending videos 1, Google's trending searches 5 and Pinterest Trends 10 (27 credits for Germany's five boards). A board the country does not have is not called and costs 0. |
| Communities (`view=communities`) | The community searches at their own price: Reddit 1 credit, a Facebook group search 1 plus 1 for each group returned with its details (up to 11), a Telegram channel search 2 plus 1 for each of up to 5 channels returned with its details, YouTube 1. The fit costs nothing against your keywords and 1 credit per started 15 communities against a `context` that differs from them. |
| Messages inside Telegram channels (`search_in.telegram=messages`) | Up to 7 credits a keyword: 2 for the channel search and 1 for each of up to 5 channels searched. A channel with no matching message costs 0. |
| Author walks (`authors_match=walk`) | One page of each listed author's own feed per platform at that feed's page price (`pages_per_platform` pages when you send it). |
| Seeds (`seeds`) | Each lookup at `prism/find-accounts`' own price (see Names to accounts). |
| `view=items` | The entity choice: 1 credit per started 25 rows judged (rows and comments that name something). Hashtags, mentions, sounds, topics, counts and growth are free. `dry_run` shows it in `estimate.by_stage.items`. |
| Filters, geo, the sponsored verdict, de-duplication, summaries, stored inputs, watermarks, replays, `include=dropped`, and reading a run | Free. |

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](/docs/errors.md) 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`).

| Code | Status | When |
| --- | --- | --- |
| `INVALID_REQUEST` | 400 | `invalid_param` (also an invalid or mismatched `cursor`), `conflicting_params`, `not_released` (with `suggested_url` on the GET), `post_only_field`, `max_credits_below_estimate`, `order_rank_while_running`, `watermark_mismatch`, `true_limit`, `input_limit`, `nothing_to_search` (the request plans no search at all, for example a marketplace with no market for `country`; `details.fields` names the field to change), `sensitive_question` (a question infers a trait of a person; `details.category` names it), `not_offered` (`include=archive` and `webhook`, see What is not offered), `unknown_feedback_ids` (a more's feedback names ids that are not this run's), `max_credits_per_month` (a more on a scheduled run asks for more than its schedule has left this month; `details.month_left`). |
| `INSUFFICIENT_CREDITS`, `KEY_BUDGET_EXCEEDED` | 402 | The balance or the key's credit limit is below what the run needs. |
| [`RUN_NOT_FOUND`](/docs/errors.md#run-not-found) | 404 | No run with this id belongs to your account. |
| [`SCHEDULE_NOT_FOUND`](/docs/errors.md#schedule-not-found) | 404 | No schedule with this id belongs to your account, or it was deleted. |
| [`RUN_STATE_CONFLICT`](/docs/errors.md#run-state-conflict) | 409 | The run's state does not allow the call, for example resuming a completed run, or `more` on a run that is not completed (`run_not_completed`). |
| [`RUN_EXPIRED`](/docs/errors.md#run-expired) | 410 | A finished run's retention passed, or the run was purged. |
| `PAYLOAD_TOO_LARGE` | 413 | The URL is too long (send a POST, or store long author lists), or a POST body is over 1 MB. |
| [`NEEDS_ASYNC`](/docs/errors.md#needs-async) | 422 | Only with `async=false`: the request is over one call's budget. `details.reason` is `legs`, `joins`, `comment_posts` or `limit`, `details.over` lists every one, and the fields behind them are in `details.causes`. |
| `UPSTREAM_ERROR` | 502 | `all_legs_failed`: nothing was collected, and nothing was charged. |
| `SERVICE_UNAVAILABLE` | 503 | `judge_unavailable` (your `questions` could not be checked, so nothing ran), `store_unavailable`, `queue_unavailable`, `idempotency_store_unavailable` or `watermark_unavailable` (`since_watermark` cannot be checked right now); retry after `Retry-After`. A POST refused with `queue_unavailable` leaves its run `failed` without running or charging it, so the same request starts a new run. |

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

## Compared with search/multi and search/everywhere

| | `/v1/prism/discover` | `/v1/search/multi` | `/v1/search/everywhere` |
| --- | --- | --- | --- |
| Date window | Applied to every row, with extra pages walked to reach a past window | `since` and `until` keep rows on every platform, on one page per platform | `from_date`, `to_date`, `since` and `until` drop rows outside the window, on one page per source |
| Judging | Every row against your keywords or your question, and duplicates removed across platforms | Relevance against the query on every row; `relevance=filter` drops off-topic rows | Reranked and clustered |
| Size | One call, or a background run of thousands of searches that you can resume | One page per platform, in one call | One call |
| Price | Each platform's own page price | Each platform's own page price | Flat 20 credits |

`/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

| Id | Limit | Nearest route |
| --- | --- | --- |
| L1 | It never infers the age, gender, affluence or another trait of an individual author. | Describe the topic in `context`; use creator audience aggregates for a whole account. |
| L2 | It has no global Telegram message search (that needs a logged-in session). | Telegram's channel search, which `platforms=telegram` runs on every view, and `search_in.telegram=messages` to search inside the channels it finds. |
| L3 | It cannot say where a Reddit user lives; Reddit publishes no country. | Community-level hints. |
| L4 | X and Reddit have no per-country trends. | Rows from the pool and Reddit's own feeds. |
| L5 | Instagram, TikTok and the other platforms except Reddit and X have no platform-wide comment search. | Comments under posts found by search (`comments=inline`); Reddit and X comment search. |
| L6 | It finds what each platform's own search returns, no more. | More keywords, hashtags and platforms. |
| L7 | It has no platform-wide history of a sound or a hashtag. | Scheduled runs with watermarks. |
| L8 | It is not a person look-up: an email address or phone number in the keywords, query, context, brands, a group's keywords, context or brand, or `authors` is a free 400 (`true_limit`, `limit: L8`). | None. |
| L9 | It does not cover TV or radio broadcasts. | News coverage of a broadcast. |
| L10 | TikTok keyword search does not reach a window older than 180 days. | Walk the posts of the accounts it found. |
| L11 | Content behind a member login (Naver cafe full text and dates, and any site measured as walled) is not read. | The search snippet, marked `text_truncated: true`, with `body_status: login_wall` and no charge. |

## 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](https://www.geonames.org/) 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.

| Field or value | Why | Instead |
| --- | --- | --- |
| `include=archive` | A stored copy of each row's image waits on a legal review of storing third-party images. | Leave it out: each row's media URLs still point to its image. |
| `webhook` | Discover's events go to the webhook endpoints registered on your account, one registration for every run. | Register once with `POST /v1/webhook-endpoints`, or read the same events with `GET /v1/events`. |

## Next steps

- [Discover for agents](/docs/prism/discover-agents.md): The two agent tools, the retry policy and three worked transcripts.
- [Find accounts](/docs/prism/discover-accounts.md): Keywords to judged accounts on seven platforms, then their posts and comments, step by step.
- [Find creators in a market](/docs/prism/discover-creators.md): Keywords to on-topic TikTok, YouTube and Instagram creators in one market, with followers and emails.
- [Market research with discover](/docs/prism/discover-research.md): A topic and market grid in one run, with the drop log and the site access table.
- [Monthly brand report](/docs/prism/discover-brand-report.md): A brand and its competitors for a month, with comments, stance and a weekly schedule.
- [Track topics and hashtags](/docs/prism/discover-topics.md): One schedule for every topic, only new posts on each run, and the hashtags you do not search yet.
- [Errors](/docs/errors.md): Every error code, with its fix.