Twitter Audience Summary API | Countries and Bot Share

Audience Summary samples up to 100 of an account's followers, or of a tweet's retweeters, reads each sampled account's About object, and returns a country histogram built from account_based_in plus a likely-bot share from seven documented profile signals. The bot share is a heuristic over profile fields, not a verdict on any account. Billed at $0.0008 per sample page fetched plus $0.0008 per sampled account X answered About for.

curl -X GET "https://example.com/user/audience_summary?username=stripe&user_id=102812444&tweet_id=1866512345678901234&source=followers&sample=50"

{  "source": "followers",  "user_id": "102812444",  "sample_requested": 50,  "sample_size": 50,  "about_answered": 48,  "countries": [    {      "country": "United States",      "count": 21,      "share": 0.477    },    {      "country": "India",      "count": 9,      "share": 0.205    },    {      "country": "United Kingdom",      "count": 6,      "share": 0.136    },    {      "country": "Germany",      "count": 5,      "share": 0.114    },    {      "country": "Brazil",      "count": 3,      "share": 0.068    }  ],  "country_known": 44,  "country_unknown": 6,  "likely_bot_count": 4,  "likely_bot_share": 0.08,  "bot_signal_counts": {    "default_profile_image": 7,    "empty_bio": 12,    "under_5_followers": 5,    "follow_ratio_over_20": 3,    "no_posts": 4,    "created_under_30_days": 2,    "digit_suffix_handle": 6  },  "bot_rule": "an account counts as likely automated when it shows 3 or more of: still has X's default profile image; no bio; fewer than 5 followers; follows over 500 accounts and more than 20 times its follower count; has never posted; account created in the last 30 days; handle ends in 6 or more digits (the auto-generated pattern)",  "pages_fetched": 2,  "billed_items": 50}

{  "error": "bad_request",  "message": "`sample` must be a whole number from 10 to 100."}

{  "error": "unauthorized",  "message": "Missing or invalid x-api-key header."}

{  "error": "insufficient_credits",  "message": "Not enough credits for 53 items. Top up, or send a smaller batch."}

{  "error": "not_found",  "message": "Could not resolve @no_such_handle."}

{  "error": "batch_in_progress",  "message": "One batch per API key at a time. Retry when the running batch returns. Not billed."}

{  "error": "upstream_unavailable",  "message": "The audience could not be sampled right now. Not billed; retry shortly.",  "upstream_status": 503}

Pricing

Billed per item, not per call: $0.0008 for each sample page that added at least one account (at most 3) plus $0.0008 for each sampled account X answered About for, found or not_found. An empty trailing page and an empty audience are not billed. A 100-account sample therefore costs at most $0.08 plus up to 3 pages ($0.0024), and billed_items in the response states the exact count. The balance is checked up front for the sample size plus 3, so sample=50 needs room for 53 items or the call returns a 402 and nothing is fetched or billed. If no sample page can be fetched at all, the call returns a 503 and nothing is billed.

When to use

Use it to size up who an audience is before you work with an account, for example checking where a creator's followers are based and how many look automated, in one call instead of paging followers and calling User About Batch yourself.

Related endpoints

• User About Batch: Fetch the About object for up to 100 accounts in one request.
• User Followers: Page through the accounts that follow a user.
• Tweet Retweeters: List the users who retweeted a tweet.

FAQ

Which audience does it sample?

Send username or user_id to sample the account's followers, or tweet_id to sample the tweet's retweeters. source is optional and only confirms the choice: source=followers takes username or user_id, source=retweeters takes tweet_id, and a source that disagrees with the identifier you sent returns a 400. Sending a user and a tweet_id together also returns a 400.

How is the sample taken?

The sample is the first distinct accounts X returns for that audience, read over up to 3 pages, until sample accounts are collected (10 to 100, default 50). It is not a random sample of the whole audience. sample_size is lower than sample_requested when the audience is smaller or the pages run out.

How are the country shares computed?

Each sampled account's About object carries account_based_in, X's account-country field. countries counts the accounts with a known country, most common first, and each share is that country's count divided by country_known, rounded to three decimals. country_unknown counts the rest of the sample: accounts with no country on X, accounts X answered not_found, and accounts whose About read failed.

How does the likely-bot count work?

An account counts as likely automated when it shows 3 or more of these 7 signals, read from the profile the sample page already returns: still has X's default profile image; no bio; fewer than 5 followers; follows over 500 accounts and more than 20 times its follower count; has never posted; account created in the last 30 days; handle ends in 6 or more digits (the auto-generated pattern). A field the profile does not carry never counts as a signal. It is a heuristic over profile fields, not a verdict on any account: a real person can trip three signals and an automated account can trip none. The default image is read from default_profile_image, or from the profile image URL when X omits that flag.

What is billed_items?

pages_fetched (pages that added at least one account) plus the number of sampled accounts X answered About for (found or not_found). An account with no followers or a tweet with no retweeters bills nothing. Multiply by $0.0008 for the charge. About reads that failed on our side or that X refused are not billed, and if the caller disconnects before the response is sent, nothing is billed.

What do the 429 and 503 errors mean here?

A 429 with error batch_in_progress means a batch on the same API key is still running (Audience Summary shares the one-batch-per-key slot with User About Batch and Check Follow Relationship Batch); it carries a Retry-After header of 5 seconds and is not billed. A 503 with error upstream_unavailable means no sample page could be fetched; it carries a Retry-After header of 5 seconds and upstream_status, and is not billed. An unknown username returns a 404 before anything is sampled.

Do fields and compact apply?

No. Audience Summary always returns its full summary object and ignores fields and compact. The body is small: one row per country plus the counters.