# Runs, results and cost (/docs/prism/discover-runs) Follow a run, read its rows, look further after it ends and see what it costs Every Discover request is a run with a `run_id`. This page covers what happens after you send it: whether it answers in the call or in the background, how to follow it, how to read and extend its rows, and what it costs. Every other request field is on [Discover request fields](/docs/prism/discover.md). ## 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. Its `estimate.min_max_credits` is the least `max_credits` the real call accepts; one credit less is refused, free, with `max_credits_below_estimate`. On a creator call with a `campaign_url` whose listing is not read yet, that read is billed before this check and the listing can raise the least cap, so it is known only once the listing is read. `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. ### 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 or did not fit a pass's time (`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. `max_credits` is the cap on everything this run and its `more` calls spend; a `more` call can raise it. `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. ## 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`. ## 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 that version, in pages: follow `pagination.next_cursor` until it is gone. On a posts or accounts run each object row carries its `version` (a `format=text` line has none), the last page names `data.changes.resume_from`, the version to read from next, and `data.next.changes_url` follows the cursor while the range has more, then reads from `resume_from`. On a posts run, a row whose author is on the suppression list, also when the author was listed after the run delivered the row, reads `{"id": "...", "removed": true, "version": N}` and nothing else, in every `author_identity`: delete the row you stored under that `id`. A post that only names a listed person is not removed. A comment by an account listed after the run delivered its row is removed from the row, and the changes read delivers the row again without it, with a new `version`: replace the row you stored. An entry removed from the list later does not bring the row back into that run. On an accounts run every delivered account row (in the GET's own answer, here and in `results.jsonl`) also carries `account_key_hash`, opaque and stable while the run can be read, and `fields` always keeps it (under `author_identity=hash` it is `account.key`; under `omit` it is absent, so replace your copy with a full read; you can match neither updates nor removals); an account since put on the suppression list, also after the run delivered it, reads `{"account_key_hash": "...", "platform": "...", "removed": true, "version": N}` and nothing else, to match on that hash; under `author_identity=omit` it reads `{"platform": "...", "removed": true, "version": N}` with no hash, so re-read the run. An account found only through a listed person's posts reads removed too, and an account whose evidence held such a post is delivered again without it. An entry removed from the list later does not bring the account back into a run that stored it suppressed; a new run finds it afresh. An items run lists every item instead. | | `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 (and the same `changes_since`) continues it. On a posts or accounts run with `changes_since`, the stream holds every changed row of the range, each object row with its `version` (a `format=text` line has none), and its last line is `{"complete":true,"resume_from":N}`, the `changes_since` to send next. `sort=` orders the export as it orders the run read. A settled posts run whose own `sort` is not `relevance`, the default, exports in that order with no parameter, so a run sent with `sort=recent` downloads newest first; send `order=arrival` for arrival order, or `order=rank` to rank any run. | | `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.=`, `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, rows come in rank order. The one exception is a settled GET run whose rows are all judged, read with no `order`, `sort` or narrowing: that read gives the rows the GET delivered first, then the rest in rank order, so its first page equals the GET's page at the same size. Send `order=rank` for pure rank order. 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 cursor from that first-page read is also refused with a free 400 naming `order=arrival` once a `resume`, `more` or `continue` lands more rows. A rank-order cursor, on the run read or the export, is refused the same way once a `more` or `resume` changes the run, because the ranked list it counts into is gone: drop `cursor` to read the new list from the start. 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..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, after the rows the GET delivered: every page is a slice of one list, those rows followed by the rest in rank order, so each kept row comes once. `page_size` sizes the page, and `limit` on a cursor read changes nothing. If the run still has rows landing or waiting on a judgment when the GET answers, the cursor walks arrival order instead, so its pages can repeat rows the GET delivered, and a cursor issued before this behavior keeps its own arrival walk the same way. A cursor is refused with a free 400 naming `order=arrival` once a `continue`, `resume` or `more` lands more rows on its run. 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..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`). ## 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. ## What it costs You pay for each platform search at that platform's own price, and for the judging you ask for. A run is billed only for what it spends. `max_credits` is the most a run may spend: a GET that sends none may spend up to 500 credits, and sending `max_credits` sets a lower or higher limit. With no `max_credits`, the limit is 500 or your balance (or what the API key's credit limit leaves), whichever is lower, and the answer's `_warnings` says when it is lower than 500. The POST must send it unless `dry_run` is true. `dry_run=true` shows the expected and the most a request can cost, free. | 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. ## Next steps - [Groups, schedules and lists](/docs/prism/discover-groups.md): Repeat a run on a schedule with only new rows. - [Judging and de-duplication](/docs/prism/discover-judging.md): Why a row was kept or dropped. - [Discover request fields](/docs/prism/discover.md): Every request field, preset and canonical request.