# How each platform is measured (/docs/prism/creators-platforms) See what each number in a creator row means and how it is worked out on each platform This page explains what [creator search](/docs/engines/find-creators.md) sends back: the run around the creators, each creator row, and how every number in a row is measured on each platform. Every field you can send is on [Request fields](/docs/prism/creators.md). ## What comes back The answer is the SocialCrawl envelope (the same JSON shape every endpoint returns): creators in `data.items`, `pagination { next_cursor, has_more }`, and `data.run`, `data.next`, `data.platforms`, `data.summary`, `data.request`, `data.market` and `_warnings`. A `202` has an empty `data.items`. Read `data.run.status`, never the HTTP code, to know where a run is. `data.run` carries `run_id`, `status` (`queued`, `running`, `paused`, `partial`, `completed`, `failed`, `cancelled`), `stopped_because`, `deduplicated`, `version`, `progress`, `estimate`, `credits { spent, by_stage, by_platform, pending_refund }` and `next_step`. While a run is `paused`, it also carries `credits_to_finish` and `suggested_max_credits`, the value to send to resume. `credits_to_finish.expected` prices the creators still owed at the plan's rate, or at what this run has paid per creator when that is higher. It also prices each paid `include` (`linked`, `authenticity`, `audience`) that delivered creators are still waiting for, at that include's price per creator. `suggested_max_credits` adds that and room for the next creator or include read to the credits spent. A run whose filters reject most of its candidates can pause again, and each pause quotes what is left. | `stopped_because` | Status | `next_step` says | `data.next` carries | | --- | --- | --- | --- | | `max_credits` | `paused` | how many creators are delivered and how many credits finish the run | `resume_url` with `suggested_max_credits` in its body | | `insufficient_credits` | `paused` | the balance ran out; delivered creators are readable free | `resume_url` with `suggested_max_credits` in its body, `top_up_url` | | `key_budget` | `paused` | the key's own credit limit was reached; raise or remove it, or reset its usage, on the API keys page, then resume. A resume while the limit is still spent is a free 402 `KEY_BUDGET_EXCEEDED` and the run does not move | `resume_url` | | `capacity` | `paused` | some searches or other calls waited for a free slot (another run on the same key is using its share, or the platform is busy) or did not fit the time of a pass; the run resumes by itself within minutes | `resume_url` | | `time` | `partial` | the GET's deadline passed and how many creators are deferred | `resume_url` (it continues in the background) | | `upstream_failures` | `partial` | which platforms failed and why | `resume_url` with `retry_failed` | | `service_unavailable` | `paused` | our side failed; the run resumes by itself within about an hour, or resume it now | `resume_url` with `retry_failed` | | `internal_error` | `partial` | delivered creators are kept; resume is free | `resume_url` | | `key_revoked` | `partial` | the API key that started the run was revoked; delivered creators are kept, and another active key of the same account resumes it | `resume_url` | | `cancelled` | `cancelled` | the run was canceled | `resume_url` | | `upstream_failures` with nothing collected | `failed` | the searches failed at the source, so nothing was collected and nothing was charged | `resume_url` with `retry_failed` | | `internal_error` or `service_unavailable` with nothing collected | `failed` | our side failed before any creator was kept; resume runs it again | `resume_url` with `retry_failed` | | none yet | `queued` | the account's background slots are busy; the run starts by itself | `status_url` | A paid `include` (`linked`, `authenticity`, `audience`) that a pass could not read keeps the run open: the creator is delivered and shown, and its include is read on the next pass. When a GET ends `paused` or `partial` for that reason, its `next_step` names `next.resume_url` and a `limits` line names the include and how many creators still wait for it. A background search keeps working toward `limit` for as long as it still finds creators. When its first pages do not give enough it reads the next page of each of its own searches, and when two pages in a row add no creator it plans new searches from your keywords and the creators it has already delivered, then reads their pages the same way, always within `max_credits`. A search whose last two pages brought no new creator to the run stops paging on its own, while the others go on. It stops at the first of these: `limit` creators delivered (`completed`), `max_credits` reached (`paused`, with `resume_url`), its sources run dry (two rounds of new searches that add no creator, or a round that plans nothing new), or its safety bound (up to 50 more pages of each search, 20 more rounds of new searches, or 6 hours from its latest start). Each start (the run, a caller's resume, or a `more`) allows up to 50 more pages of each search, up to 20 more rounds of new searches, and up to 6 hours. A `more` without `new_searches`, and a resume of one, reads pages only. The automatic resume after an outage of ours starts nothing again. A dry run never reports the safety bound. A search that fails at its source (a rate limit, a quota, an outage) never reads as "no more creators": the run pauses `service_unavailable`, names the search in a `limits` line, and resumes by itself to run that search again (a search the source's circuit breaker skipped is tried with one search first); nothing that failed is charged. If the source is still down after the automatic resumes, the run stays paused with that line, and `resume_url` tries again. A run that ends with fewer creators than `limit` without being paused is `completed` (or `partial`, when work is left that no lookup does) and says why in `summary.short_reason`, and whether looking further would help in `summary.more_available`. Its `next_step` and its `limits` line say the same in one sentence, starting "The run is complete: 640 of 1000 creators are here". A background `depth=quick` search fills toward `limit` the same way a `standard` one does. | `summary.short_reason` | Meaning | | --- | --- | | `candidates_exhausted` | The run ran out of candidates before `limit`. | | `low_yield` | The last creators looked up rarely passed your filters. `summary.pass_rate` is the measured share that passed. | | `null` | The run met `limit`, or it paused. | | `summary.more_available` | Meaning | What to call next | | --- | --- | --- | | `false` | The run has finished looking. When two rounds of new searches found no new creators, its `next_step` says "This run has finished: two rounds of new searches found no new creators, so searching further is unlikely to find more. To widen it, start a run with other keywords, platforms or filters." When the last round planned nothing new, or no round and no page was left to try, it says "This run has finished: there are no new searches left to try for this request, so searching further is unlikely to find more. To widen it, start a run with other keywords, platforms or filters." Its `limits` line starts `{n} of {limit} creators: ` with the same reason. | Nothing from this run. To widen it, start a run with other keywords, platforms or filters. | | `true` | More can still be found: the run stopped at its safety bound with work left (its `limits` line names the bound, and says "while it was still finding creators" only when its latest step found some; otherwise it names what is still unread), or it could not plan new searches. `more_available` true means a `more` call can find more: send `next.more_url` with `next.more_url.body` (`{}` reads more pages, `{ "new_searches": true }` also plans new searches). | POST `next.more_url` with the body it carries. Add `new_searches: true` and `feedback { accept, reject }` of account keys to steer new searches, and `dry_run: true` to price it first, free. Each page bills at its own price within `max_credits`. | | `null` | The run is not a completed short run: it met `limit`, or it paused, where `resume_url` is the next call. It is also `null` for a run that measured a given list of handles (`handles` or `author_list_id`) and has no searches of its own. | Follow `next_step`. | A run that measured a list of handles has no searches to read to the end, so it never settles `false`. When it ends short, its `next_step` and `limits` line say how many handles were kept ("3 of 5 handles were kept; each dropped one carries its drop_reason, readable with state=dropped."), and `next.more_url` looks for more creators on the same topics as the ones kept. When the run was `true` but no search has a next page left past its bound (50 pages from the run's latest start), only new searches would find more, so the ready body of `next.more_url` is `{ "new_searches": true }`. A completed run also carries `next.more_url`. The GET answered in the call never fills past its budget: when the request is larger, its `next_step` points at the background form. ### A creator Each creator is the same account row discover returns, with the creator blocks filled. An unmeasured block is `null` with an entry in `missing`; in `compact` it is left out. ```json title="A creator (format=evidence, trimmed)" { "account": { "key": "tiktok:lafernandaai", "platform": "tiktok", "username": "lafernandaai", "followers": 36683, "followers_label": "followers", "followers_approximate": false, "url": "https://www.tiktok.com/@lafernandaai", "languages": [{ "code": "es", "share": 0.9 }], "country": { "value": "CL", "name": "Chile", "source": "post_region", "confidence": 1 }, "activity": { "last_post_at": "2026-10-23T18:04:11Z", "posts_30d": 6 }, "metrics": { "median_views": 179269, "mean_views": 251400, "median_shares": 1900, "median_saves": 2100, "engagement_rate": 0.074, "basis": "views", "posts_per_week": 0.6, "posts_used": 10, "pinned_excluded": 0, "low_sample": false, "methodology_version": "creator-metrics-v1" }, "signals": { "views_to_followers": 4.89, "like_to_comment": 32.2, "engagement_vs_benchmark": 0.78, "pinned_share": 0 }, "sponsored_history": { "posts_checked": 10, "disclosed": 0, "brands": [], "last_seen": null, "evidence": [] }, "linked_accounts": [{ "key": "instagram:lafernandaai", "link_basis": "profile_link", "confidence": 0.9 }] }, "judgments": { "fit": { "p": 0.99 }, "account_kind": "individual_creator", "automated_decision": false }, "score": { "value": 0.75, "components": { "fit": 0.99, "engagement": 0.39, "activity": 0.6, "reach": 1 }, "weights_version": "creator-score-v1", "basis": ["fit", "engagement", "activity", "reach"], "flagged": [] }, "why": { "matched_filters": [{ "field": "min_followers", "value": 10000, "measured": 36683 }], "matched_posts": ["7562001184421022982"], "judgment_basis": "evidence and 10 walked captions", "unapplied_filters": [] }, "status": { "profile": "ok", "posts": "ok", "judgment": "ok" }, "missing": [], "state": "kept", "drop_reason": null } ``` The values show the shape. `score.value` weighs fit 0.45, engagement 0.30, activity 0.15 and reach 0.10 over the components present; reach is 1 for every creator when you send a size band. Contact values appear only with `include=contacts`, and the measured posts only with `include=posts`. With `include=linked`, each delivered creator is checked once by `prism/creator-card?verify=true` anchored on its own platform, at 5 credits a creator (billed with the profile lookups, in `credits.by_stage.enrich`): an account the identity check judges the same person is marked `"identity": "same"` in `linked_accounts` (`link_basis: same_handle` when the creator does not link it itself), `linked_totals` adds followers over those platforms only (`verified_on`, `combined_followers`) and reports the rest as `unverified_followers`, and a same-handle account judged anything else is listed in `linked_totals.candidates`, never as a link. Rows are never merged across platforms. `format=compact` (about 120 to 160 tokens a creator) keeps the key, platform, username, url, followers with their label, country, median views, engagement rate with its basis, posts per week, last post, kind, fit, score, the first matched post, contact kinds and `why`. `format=text` is one line a creator: `[score] platform @username (followers with their label, median views, ER basis) country kind url`. With `include=authenticity`, each delivered TikTok, Instagram or YouTube creator gets comment-based and brand-safety signals, read on the posts the run already walked, so its profile and posts are never bought again. `account.authenticity` carries `posts_sampled` (of the first 3 walked posts, those whose comments were read), `comments_read`, `commenters` (`sampled_commenters`, the commenter profiles read; `low_quality_share`, the share of them with under 50 followers, no avatar or no posts; `median_commenter_followers`), `comment_quality` (`sample_size`, `judged`, `generic_share` and `repeated_share`), `controversy_inputs` (what news, Reddit and Hacker News searches on the handle returned) and `brand_safety` (`items_found`, `items_judged`, `namesakes_excluded`, `uncertain_items`, `level` and `flagged_items`, each citing the row it came from by `source` and `index`). They are signals with their sample sizes, never a verdict about the creator: read each share beside the count it was taken on, and open a flagged item before acting on it. `warnings` names a judgment that did not answer in full, and its block is then `null`. The reads bill at their own public prices with the profile lookups (`credits.by_stage.enrich`) and the judging pass with account judging (`credits.by_stage.judge_accounts`); a creator a pass could not measure says why in `missing` (`field: authenticity`), and a later pass of a background run measures it. With `author_identity=omit` or `hash`, a flagged item keeps its category and severity and drops its link. With `include=audience`, each delivered TikTok creator is read once through `tiktok/user/audience` at 5 credits (billed with the profile lookups, in `credits.by_stage.enrich`; 0 when TikTok publishes nothing for it), and `account.audience` carries what TikTok publishes about the creator's followers: `countries` (each with `country_code`, its sampled `count` and its `share`), `n` (the followers sampled, the sum of the counts) and, where TikTok's creator marketplace publishes them, `genders` and `ages` with their shares exactly as published, which need not add to 1 (`facets_basis` says where they come from; they are `null` otherwise). It is a sample of followers as published, a few hundred followers or about 1,300 for the largest creators, so read each share beside `n`. It describes the creator's followers, never the creator: the creator's own `country`, `languages` and `account_kind` never come from it. `audience_country=GB:0.3` keeps only TikTok creators whose sampled followers are at least that share in the country; every floor you send must hold, and a country TikTok does not list counts as 0. The read is the dearest step a creator takes, so it runs after every other filter and before delivery, for creators that would otherwise be delivered; a creator it drops shows `drop_reason: audience_country` with its audience under `state=dropped`, and a creator TikTok publishes nothing for, or whose audience read goes unanswered on two passes, is dropped `audience_unknown` (`unmeasurable` does not apply to audience reads). Without `platforms`, `audience_country` searches TikTok alone; with any other platform it answers a free 400 `not_released` with no `release` (no platform but TikTok publishes an audience) and a `suggested_url` that searches TikTok, and so does `include=audience` on a request that searches no TikTok. Gender and age are never filters. ### Words a reader meets - `state` (`kept` or `dropped`) says whether a creator passed this run's filters; it is not a recommendation. A creator the run found but has not looked up yet (a `limit` met first, or a run paused at its cap) reads as `pending`: it is not counted as delivered, and a resume or `more` with a higher `limit` can still deliver it. - `status.profile`, `status.posts` and `status.judgment` say how far each stage got for a creator: - `ok`: the stage ran and answered. - `pending`: the stage has not been reached yet; a resume or the run's next pass reaches it. - `deferred`: the stage was cut off by a deadline, or a first failed walk waits for the next pass; it is resumable. - `skipped_cap`: the creator was not looked up in this call because the call's budget was spent; a resume looks it up in the background. - `partial`: the stage ran in part. `status.judgment: partial` means the creator was not judged in this call and carries null judgments until a resume judges it. - `unverified`: the source could not verify the account. It is looked up once more, and a creator still unverified after two lookups is dropped with `drop_reason: unverified`. - `not_found`: the platform says the account does not exist, and the creator is dropped `not_found`. - `unsupported`: the platform has no lookup or no posts walk for this account, so the stage cannot run. - `error`: the stage ran and failed. `status.posts: error` is a walk that failed on two passes: the creator's `metrics` are `null` with `missing` reason `not_published`, and `unmeasurable` decides each metric floor and `active_within_days` (`keep` delivers it flagged in `why.unapplied_filters`, `drop` drops it `metric_not_published`). - `off`: the stage was not asked for, such as the posts walk on `depth=quick`, or judging with `label=none` or on a `handles` run without `context`. - `drop_reason` names the filter a dropped creator failed, such as `min_followers`, `country_unknown`, `account_kind_unknown`, `metric_not_published` (with `unmeasurable=drop`), `metric_unknown` (a floor whose value is still unknown after the walk, the metric named in `missing`) or `sponsor_excluded`. `over_limit` marks a creator that passed every filter but ranked past `limit`: a run looks up a few more creators than `limit` so that it can still fill `limit` when some fail, and it delivers only the top `limit`. A resume or `more` that raises `limit` puts those creators back in the running without buying anything for them again; a creator you rejected in `feedback.reject` never comes back. Read them with `state=dropped`. - `summary.empty_reason` is present whenever nothing is delivered: `no_matches`, `filtered` (with the filter that removed most), `relevance_filtered`, `market_filter_only`, `source_empty_unverified` or `not_reached` (candidates are still pending on a paused or partial run). - `by_country.hinted` counts creators whose country was read from text, neither declared nor a post region; a hinted country never keeps a creator under `unknown_country=drop`. ## How each platform is measured Every metric is computed the same way on every platform: pinned posts and reposts are left out, rates are sums over sums, and a count a platform does not publish is `null` with `missing: not_published`. `low_sample` is `true` when fewer than 5 posts carry the count. | Platform | Posts walked | Engagement basis | Shares | Saves | | --- | --- | --- | --- | --- | | TikTok | profile videos | views | yes | where published | | Instagram | profile reels, read with `include=stats` | followers (the views basis over reels is reported beside it) | reels | reels read with `include=stats`; none on photos and carousels | | YouTube | channel videos and shorts, measured apart in `metrics.by_format` | views | no | no | | X | profile posts, retweets left out | followers | reposts | bookmarks where published | | LinkedIn | profile posts, reshares left out | followers | reposts | no | | Threads | profile posts | followers | reposts | no | | Facebook | page or profile posts | followers | not carried by the walk | no | Instagram saves are measured on reels, which the walk reads with `include=stats` (on two creators measured on 27/10/2026, every reel carried its saves); photos and carousels from the post grid carry no save count. LinkedIn posts publish no view counts and Instagram photos publish none, so a views floor is not applied there: the creator is delivered flagged in `why.unapplied_filters`, or dropped with `unmeasurable=drop`. On YouTube, `video_format=long` or `short` chooses which videos the view metrics read. On Instagram, `posts_per_creator` counts reels: the walk reads each creator's reels feed (with `include=stats`, 10 reels a page) and measures the latest reels that are not pinned or reposts, so `posts_per_creator=20` means the latest 20 reels, which is 2 pages. Photos and carousels are not walked, so they add nothing to the count and no saves to `median_saves`; `metrics.posts_used` says how many reels were measured. A GET answered in the call walks at most 12 posts per creator, whatever `posts_per_creator` says, and its `limits` says so; send `async=true` or a POST to walk them all. Threads and Facebook are searched when you name them in `platforms` (`platforms=threads,facebook`); the default platforms stay TikTok, Instagram and YouTube. Threads creators are found by what they post (Threads post search) and by name (Threads account search); Facebook creators by what they post and by page search. Threads posts walked from a profile carry no view count, so a views floor is not applied on Threads: the creator is delivered flagged in `why.unapplied_filters`, or dropped with `unmeasurable=drop`. Facebook carries views on videos only, so `median_views` there is the median over the creator's videos. Threads profiles state no country; a Threads creator's country can only be hinted from its links, so a `country` search keeps Threads creators only with `unknown_country=keep`. A Facebook page's country comes from the address the page publishes, when it publishes one. A Facebook personal profile, unlike a page, publishes no follower count: such a creator is delivered with `followers: null` and no followers-basis engagement rate, and a `min_followers` floor drops it. Lookalikes on Threads and Facebook come from the seed's topics (`similar: "topic_only"`). ## Grade a roster you already have ```json title="Request body" { "handles": ["instagram:", "..."], "purpose": "creator", "posts_per_creator": 20, "sort": "median_shares", "max_credits": 1000 } ``` Send it to `POST /v1/prism/creators` with up to 1,000 handles. `limit` defaults to the number of handles, and every handle comes back `kept` or `dropped` with its reason. Instagram reels are read with `include=stats` (1 credit a page more), which carries the shares and saves of each reel, so `median_shares` and `median_saves` are measured on the reels; a photo or carousel from the plain post grid carries no save count. TikTok carries both where it publishes them. A handle is one creator however it is written: letter case (except a YouTube channel id, a TikTok sec_uid or a Facebook pfbid) and a profile URL in place of the handle do not make it a different creator, so they never start a second run. For more creators, store the list once with `POST /v1/prism/discover/inputs` (`{ "kind": "authors", "authors": [...] }`, up to 10,000 handles, free, kept 30 days) and send its `author_list_id` with `purpose` in place of `handles`. Every entry of the list is measured: `limit` defaults to the number of entries, the dry run prices them all, and every creator comes back `kept` or `dropped` with its reason. An entry that names no creator, or repeats one listed earlier, is never looked up or charged, and `_warnings` says how many there were with the first of them. A run of this size continues in the background for hours: read it with `wait_s`, or take every creator at once from `results.jsonl?state=all&order=arrival`, which streams one line per creator and ends with `{"complete": true}` (ranked, a read holds the first 5,000 creators and its first line says so). Searches deliver up to 1,000 creators with `limit` in the background; the GET still answers at most 100 in the call. ## Why is a value unknown? A creator whose country, kind or metric cannot be measured is kept or dropped by `unknown_country`, `unknown_kind` and `unmeasurable`. [Why the defaults differ](/docs/prism/creators.md#why-the-unknown-value-defaults-differ) explains each default. ## Next steps - [Request fields](/docs/prism/creators.md): Every field, price and error of creator search. - [Markets, niches and size](/docs/prism/creators-markets.md): Narrow creator search by country, niche and followers. - [Follow creators](/docs/prism/creators-follow.md): Save the creators you found and hear when they post.