User Reads

Audience Summary

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.

get/user/audience_summary

Request

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

Query parameters

usernamestring

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.

Example:stripe
user_idstring

Numeric ID whose followers are sampled, as an alternative to username. Used as sent, with no lookup.

Example:102812444
tweet_idstring

Numeric tweet ID whose retweeters are sampled, instead of a user's followers. Cannot be combined with username or user_id.

Example:1866512345678901234
sourcestring

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.

Example:followers
sampleinteger

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

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

sourcestring

The audience sampled: followers or retweeters.

user_idstring

Numeric ID of the account whose followers were sampled. Present when source is followers.

tweet_idstring

The tweet whose retweeters were sampled. Present when source is retweeters.

sample_requestedinteger

The sample size you asked for (the sample parameter, default 50).

sample_sizeinteger

Distinct accounts actually sampled. Lower than sample_requested when the audience is smaller or the pages ran out.

about_answeredinteger

Sampled accounts X answered an About read for, found or not_found. Each is billed.

country_knowninteger

Sampled accounts whose About read returned a country.

country_unknowninteger

sample_size minus country_known: accounts with no country on X, accounts answered not_found, and accounts whose About read failed.

likely_bot_countinteger

Sampled accounts showing 3 or more of the 7 bot signals. A heuristic over profile fields, not a verdict on any account.

likely_bot_sharenumber

likely_bot_count divided by sample_size, rounded to three decimals. 0 when nothing was sampled.

bot_rulestring

The likely-bot rule in plain words: the threshold and the 7 signals, exactly as applied to this response.

pages_fetchedinteger

Sample pages that added at least one account, at most 3. Each is billed; an empty trailing page is not counted.

billed_itemsinteger

pages_fetched plus about_answered: the items this call was billed for. Multiply by $0.0008 for the charge.

Changes

No recorded changes to this operation across all 1 revision of this API.