SocialCrawl
EnginesDiscover

Runs, results and cost

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.

One call or a background run?

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

StatusMeaningWhat to do
queuedWaiting for a free slot: your account already runs ten background runs. It starts on its own.Wait on next.status_url; never resubmit.
runningCollecting, judging or delivering.Wait on next.status_url; read rows as they arrive.
pausedStopped 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.
partialFinished 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.
completedFinished.Read every kept row at next.results_url, free; POST next.more_url for more.
failedNothing 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.
cancelledStopped 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.

CallWhat it does
GET /v1/prism/discover/runsYour 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=25Status, 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.jsonlEvery 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}/legsEvery 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}/resumeContinues 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, 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.<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, 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.<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.
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.

ItemPrice
A platform searchThe 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 keywordsFree. 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 keywords1 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 rows1 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_to1 credit per started 1,000 translated characters.
sitesPer 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=autoPer 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=walk1 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=suggestionsEach 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 searches5 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=bodyThe 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_countryOne 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=interest5 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=itemsThe 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 runFree.

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

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

Errors

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

CodeStatusWhen
INVALID_REQUEST400invalid_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_EXCEEDED402The balance or the key's credit limit is below what the run needs.
RUN_NOT_FOUND404No run with this id belongs to your account.
SCHEDULE_NOT_FOUND404No schedule with this id belongs to your account, or it was deleted.
RUN_STATE_CONFLICT409The 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_EXPIRED410A finished run's retention passed, or the run was purged.
PAYLOAD_TOO_LARGE413The URL is too long (send a POST, or store long author lists), or a POST body is over 1 MB.
NEEDS_ASYNC422Only 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_ERROR502all_legs_failed: nothing was collected, and nothing was charged.
SERVICE_UNAVAILABLE503judge_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