---
title: "Audience Summary"
method: GET
path: "/user/audience_summary"
tags: ["User Reads"]
---

# Audience Summary

`GET /user/audience_summary`

## Request

- Base URL: `https://api.twitterapis.com/twitter`
- URL: `https://api.twitterapis.com/twitter/user/audience_summary`
- Auth: HTTP bearer

Sample up to 100 of an account's followers, or of a tweet's retweeters, read each sampled account's About object, and return a country histogram of account_based_in with each country's share of the accounts whose country is known. The response also counts how many sampled accounts show each of seven documented profile signals and how many show three or more (likely_bot_count), a heuristic over profile fields rather than a verdict on any account. Cost: $0.0008 per billed item.

## Query parameters

- `username` string: Handle whose followers are sampled, with or without the leading @. Send username, user_id, or tweet_id. An unknown handle returns a 404 and nothing is billed.
- `user_id` string: Numeric ID whose followers are sampled, as an alternative to username. Used as sent, with no lookup.
- `tweet_id` string: Numeric tweet ID whose retweeters are sampled, instead of a user's followers. Cannot be combined with username or user_id.
- `source` string: Optional confirmation of the audience: followers (with username or user_id) or retweeters (with tweet_id). When sent, it must agree with the identifier, or the request returns a 400.
- `sample` integer: How many distinct accounts to sample, a whole number from 10 to 100. Default 50. Also sets the balance needed up front: sample plus 3 items.

## Response `200`

Summarize a sample of an account's followers or a tweet's retweeters by country and likely-bot share.

- object
  - `source` string: The audience sampled: followers or retweeters.
  - `user_id` string: Numeric ID of the account whose followers were sampled. Present when source is followers.
  - `tweet_id` string: The tweet whose retweeters were sampled. Present when source is retweeters.
  - `sample_requested` integer: The sample size you asked for (the sample parameter, default 50).
  - `sample_size` integer: Distinct accounts actually sampled. Lower than sample_requested when the audience is smaller or the pages ran out.
  - `about_answered` integer: Sampled accounts X answered an About read for, found or not_found. Each is billed.
  - `countries` object[]: Country histogram over the sampled accounts with a known account_based_in, most common first (ties in alphabetical order).
    - `country` string: The country, as X reports it in account_based_in.
    - `count` integer: Sampled accounts based in this country.
    - `share` number: count divided by country_known, rounded to three decimals. Shares are over accounts with a known country, not over the whole sample.
  - `country_known` integer: Sampled accounts whose About read returned a country.
  - `country_unknown` integer: sample_size minus country_known: accounts with no country on X, accounts answered not_found, and accounts whose About read failed.
  - `likely_bot_count` integer: Sampled accounts showing 3 or more of the 7 bot signals. A heuristic over profile fields, not a verdict on any account.
  - `likely_bot_share` number: likely_bot_count divided by sample_size, rounded to three decimals. 0 when nothing was sampled.
  - `bot_signal_counts` object: How many sampled accounts show each signal, one key per signal. A field the profile does not carry never counts; the default image is read from default_profile_image, or from the profile image URL when X omits that flag.
    - `default_profile_image` integer: Accounts that still have X's default profile image.
    - `empty_bio` integer: Accounts with no bio.
    - `under_5_followers` integer: Accounts with fewer than 5 followers.
    - `follow_ratio_over_20` integer: Accounts that follow over 500 accounts and more than 20 times their follower count.
    - `no_posts` integer: Accounts that have never posted.
    - `created_under_30_days` integer: Accounts created in the last 30 days.
    - `digit_suffix_handle` integer: Accounts whose handle ends in 6 or more digits (the auto-generated pattern).
  - `bot_rule` string: The likely-bot rule in plain words: the threshold and the 7 signals, exactly as applied to this response.
  - `pages_fetched` integer: Sample pages that added at least one account, at most 3. Each is billed; an empty trailing page is not counted.
  - `billed_items` integer: pages_fetched plus about_answered: the items this call was billed for. Multiply by $0.0008 for the charge.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `402`: Insufficient credits
- `404`: Not found
- `429`: Rate limited
- `503`: HTTP 503

---

[API](https://skmtc.dev/twitterapis/apis/twitterapis-api.md) · [All operations](https://skmtc.dev/twitterapis/apis/twitterapis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/twitterapis/apis/twitterapis-api/revisions/a33ce0fedb3c?raw)