How each platform is measured
See what each number in a creator row means and how it is worked out on each platform
This page explains what creator search 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.
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.
{
"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(keptordropped) 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 (alimitmet first, or a run paused at its cap) reads aspending: it is not counted as delivered, and a resume ormorewith a higherlimitcan still deliver it.status.profile,status.postsandstatus.judgmentsay 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: partialmeans 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 withdrop_reason: unverified.not_found: the platform says the account does not exist, and the creator is droppednot_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: erroris a walk that failed on two passes: the creator'smetricsarenullwithmissingreasonnot_published, andunmeasurabledecides each metric floor andactive_within_days(keepdelivers it flagged inwhy.unapplied_filters,dropdrops itmetric_not_published).off: the stage was not asked for, such as the posts walk ondepth=quick, or judging withlabel=noneor on ahandlesrun withoutcontext.
drop_reasonnames the filter a dropped creator failed, such asmin_followers,country_unknown,account_kind_unknown,metric_not_published(withunmeasurable=drop),metric_unknown(a floor whose value is still unknown after the walk, the metric named inmissing) orsponsor_excluded.over_limitmarks a creator that passed every filter but ranked pastlimit: a run looks up a few more creators thanlimitso that it can still filllimitwhen some fail, and it delivers only the toplimit. A resume ormorethat raiseslimitputs those creators back in the running without buying anything for them again; a creator you rejected infeedback.rejectnever comes back. Read them withstate=dropped.summary.empty_reasonis present whenever nothing is delivered:no_matches,filtered(with the filter that removed most),relevance_filtered,market_filter_only,source_empty_unverifiedornot_reached(candidates are still pending on a paused or partial run).by_country.hintedcounts creators whose country was read from text, neither declared nor a post region; a hinted country never keeps a creator underunknown_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 |
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 |
| profile posts, reshares left out | followers | reposts | no | |
| Threads | profile posts | followers | reposts | no |
| 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
{
"handles": ["instagram:<handle>", "..."],
"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 explains each default.
