Botometer® checks the activity of a Twitter account and gives it a score based on to extent to which it matches accounts that use automation. Higher scores indicate activities that are more bot-like.

API endpoints

Botometer-V4

Overview

Endpoint: Check account (/4/check_account).

Reference: Mohsen Sayyadiharikandeh, Onur Varol, Kai-Cheng Yang, Alessandro Flammini, Filippo Menczer. “Detection of Novel Social Bots by Ensembles of Specialized Classifiers.” Proc. CIKM 2020. Preprint: Arxiv

This endpoint offers the V4 of Botometer, the same as botometer.org. The endpoint flow works generally like this:

1. You use the Twitter REST & Search APIs to obtain user info and tweets from the account you want to analyze.
2. You POST the Twitter data to this endpoint in JSON format.
3. The API analyzes the data, scores it, and returns the results in JSON format.

Request Object

To analyze an account, POST the required Twitter data as JSON to the /4/check_account endpont. Your request must supply the x-rapidapi-key header as demonstrated below.

The request object looks roughly like this (note the ellipses):

{
  "user": {
    "id": "1234567890",
    "screen_name": "IUNetSci"
  },
  "timeline": [
    {
      "id": 1234567890,
      "text": "@Botometer is so cool!",
      "...": "..."
    },
    "..."
  ],
  "mentions": [
    {
      "id": 9876543210,
      "text": "@OSoME_IU is also cool!",
      "...": "..."
    },
    "..."
  ]
}

This object has three main parts:

• User is derived from Twitter’s GET users/show REST endpoint using the target account’s screen name or ID. Only the id (or id_str) and screen_name properties are required, but you may submit the whole user object if you would like it returned to you in the response.
• Timeline is the array of Tweet objects obtained from Twitter’s GET statuses/user_timeline endpoint using the target account’s screen name or ID. Make sure to include the count=200 and include_rts=true parameters in your Twitter API request! Submit the most recent 200 statuses from the timeline, or the entire timeline if it contains fewer than 200 tweets.
• Mentions comes from Twitter’s Search API, specifically searching for the target account’s screen name and obtaining the statuses property of the Search API response. This is an array of Tweet objects. Note that your Twitter API search parameters should contain q=@... in order to search for retweets and mentions of the target account, and also count=100 to get the max number of tweets we can in one call. Submit 100 tweets from the search, or all of the tweets if it contains less than 100 tweets.

For testing purposes, you can download a full example payload as a gzipped JSON file.

Response Object

A successful classification result looks like this:

{
    "cap": {
        "english": 0.8018818614025648,
        "universal": 0.5557322218336633
    },
    "display_scores": {
        "english": {
            "astroturf": 0.0,
            "fake_follower": 4.1,
            "financial": 1.5,
            "other": 4.7,
            "overall": 4.7,
            "self_declared": 3.2,
            "spammer": 2.8
        },
        "universal": {
            "astroturf": 0.3,
            "fake_follower": 3.2,
            "financial": 1.6,
            "other": 3.8,
            "overall": 3.8,
            "self_declared": 3.7,
            "spammer": 2.3
        }
    },
    "raw_scores": {
        "english": {
            "astroturf": 0.0,
            "fake_follower": 0.81,
            "financial": 0.3,
            "other": 0.94,
            "overall": 0.94,
            "self_declared": 0.63,
            "spammer": 0.57
        },
        "universal": {
            "astroturf": 0.06,
            "fake_follower": 0.64,
            "financial": 0.3133333333333333,
            "other": 0.76,
            "overall": 0.76,
            "self_declared": 0.74,
            "spammer": 0.47
        }
    },
    "user": {
        "majority_lang": "en",
        "user_data": {
            "id_str": "11330",
            "screen_name": "test_screen_name"
        }
    }
}

Meanings of the elements in the response:

• user: Twitter user object (from the request) plus the language inferred from the majority of tweets
• raw scores: bot scores in the [0,1] range, both English (using all features) and Universal (using only language-independent features); in each case we have the overall score and the sub-scores for each bot class (see below for subclass names and definitions)
• display scores: same as raw scores, but in the [0,5] range
• cap: Complete Automation Probability (CAP) is the conditional probability that accounts with a score equal to or greater than this are automated; based on inferred language

Bot types:

• fake_follower: bots purchased to increase follower counts
• self_declared: bots from botwiki.org
• astroturf: manually labeled political bots and accounts involved in follow trains that systematically delete content
• spammer: accounts labeled as spambots from several datasets
• financial: bots that post using cashtags
• other: miscellaneous other bots obtained from manual annotation, user feedback, etc.

BotometerLite

Overview

Endpoint: Check accounts in bulk (/litev1/check_accounts_in_bulk).

Reference: Yang, Kai-Cheng, Onur Varol, Pik-Mai Hui, and Filippo Menczer. “Scalable and generalizable social bot detection through data selection.” In Proceedings of the AAAI Conference on Artificial Intelligence, vol. 34, no. 01, pp. 1096-1103, 2020. DOI:10.1609/aaai.v34i01.5460

This endpoint offers the BotometerLite model. The endpoint flow works generally like this:

1. You use the Twitter Streaming, Search, or User lookup endpoints to obtain the tweets or user profiles from a set of accounts you want to analyze.
2. You POST the data to this endpoint in JSON format.
3. The API analyzes the accounts, scores them, and returns our results in JSON format.

Request Object

To analyze the accounts, POST the required data as JSON to the /litev1/check_accounts_in_bulk endpont. Your request must supply the x-rapidapi-key header as demonstrated below.

If you have a collection of tweets from Twitter, the request object looks roughly like this:

[tweet1, tweet2, ...]

where tweet1, tweet2, … are the tweet objects you collected from Twitter without modification.
The list should contain no more than 100 tweets.

If you only have a collection of user objects (i.e. you collected them using the Twitter user lookup endpoint), the request object should look like this:

[
    {
        "created_at": "Wed Jun 05 21:42:20 +0000 2019", 
        "user":  { 
                 "id": 1234,
                 "screen_name": "test_user_1",
                 "....": "...."
             }
    },
    {
        "created_at": "Wed Aug 04 21:42:20 +0000 2020", 
        "user":  { 
                 "id": 12345,
                 "screen_name": "test_user_2",
                 "....": "...."
             }
    },
    ....
]

Notes:

• The created_at field is required and should be the time stamp of when the user object was collected.
• The user object is required and should be the profile of a target account.
• The list should contain no more than 100 elements.

Response Object

[
    {"botscore": 0.65, "tweet_id": "235135",  "user_id": 1234},
    {"botscore": 0.29, "tweet_id": "235134", "user_id": 12345}
]

For each tweet posted to the API, a corresponding object with the user_id, tweet_id, and bot score will be returned unless some errors occurred.
Note that if you follow the second example above where only the user objects are posted, the tweet_ids in the response will be set to null.

Rate Limits

Botometer-V4

The Botometer-V4 endpoint is available in all plans.

• Our BASIC rate limit is set at 500 requests per day, per user. This plan is mainly for testing. If you desire a higher daily rate limit, faster response times, and/or the ability to exceed the daily rate limit, please subscribe to the PRO or ULTRA plans.
• The PRO has no subscription fee. You will, however, need to enter a valid credit card. It provides a rate limit of 2,000 requests per day, and you go beyond the rate limit for $1/1k requests.
• The ULTRA plan imposes a subscription fee of $50 per month. In return, it provides a rate limit of 17,280 requests per day, which reflects the Twitter Search API’s user-authenticated rate limit. The plan also enables users to exceed their daily quota for $1/1k requests. (Note that Twitter’s app-only authentication allows for a higher rate limit.)

Users are free to switch between the plans at will without having to change the endpoint in their code.

BotometerLite

The BotometerLite endpoint is only available through the ULTRA plan, which provides a rate limit of 200 requests per day and allows the users to exceed the quota for $1/100 requests.
Note that each request allows checking up to 100 accounts.

For answers to questions about the Botometer service in general, please refer to our website’s FAQ.

Using botometer-python

You can simplify the usage of the Botometer Pro API with our botometer-python client library.

To check higher volumes of accounts, you may also want to use app-only authentication with the Twitter API. For complete info, see this wiki page on our GitHub repo.

Why two APIs?

When adding a paid API option, Mashape requires all users – even free users – to provide a credit card. Since we value the ability for our users to use our free service without entering their CC info, we’re forced to have two separate APIs.

Using botometer-python

You can easily use the Pro API with our botometer-python client library by specifying botometer_api_url in the constructor:

botometer_api_url = 'https://botometer-pro.p.mashape.com'
bom = botometer.Botometer(botometer_api_url=botometer_api_url,
                          wait_on_ratelimit=True,
                          mashape_key=mashape_key,
                          **twitter_app_auth)

In order to make use of the higher ratelimits allowed with the paid tier of the Pro API, you probably also want to use app-only authentication for the Twitter API. For complete info, see this wiki page on our GitHub.

Botometer Pro Overview

API endpoints

Botometer-V4

Overview

Endpoint: Check account (/4/check_account).

Reference: Mohsen Sayyadiharikandeh, Onur Varol, Kai-Cheng Yang, Alessandro Flammini, Filippo Menczer. “Detection of Novel Social Bots by Ensembles of Specialized Classifiers.” Proc. CIKM 2020. Preprint: Arxiv

This endpoint offers the V4 of Botometer, the same as botometer.org. The endpoint flow works generally like this:

1. You use the Twitter REST & Search APIs to obtain user info and tweets from the account you want to analyze.
2. You POST the Twitter data to this endpoint in JSON format.
3. The API analyzes the data, scores it, and returns the results in JSON format.

Request Object

To analyze an account, POST the required Twitter data as JSON to the /4/check_account endpont. Your request must supply the x-rapidapi-key header as demonstrated below.

The request object looks roughly like this (note the ellipses):

{
  "user": {
    "id": "1234567890",
    "screen_name": "IUNetSci"
  },
  "timeline": [
    {
      "id": 1234567890,
      "text": "@Botometer is so cool!",
      "...": "..."
    },
    "..."
  ],
  "mentions": [
    {
      "id": 9876543210,
      "text": "@OSoME_IU is also cool!",
      "...": "..."
    },
    "..."
  ]
}

This object has three main parts:

• User is derived from Twitter’s GET users/show REST endpoint using the target account’s screen name or ID. Only the id (or id_str) and screen_name properties are required, but you may submit the whole user object if you would like it returned to you in the response.
• Timeline is the array of Tweet objects obtained from Twitter’s GET statuses/user_timeline endpoint using the target account’s screen name or ID. Make sure to include the count=200 and include_rts=true parameters in your Twitter API request! Submit the most recent 200 statuses from the timeline, or the entire timeline if it contains fewer than 200 tweets.
• Mentions comes from Twitter’s Search API, specifically searching for the target account’s screen name and obtaining the statuses property of the Search API response. This is an array of Tweet objects. Note that your Twitter API search parameters should contain q=@... in order to search for retweets and mentions of the target account, and also count=100 to get the max number of tweets we can in one call. Submit 100 tweets from the search, or all of the tweets if it contains less than 100 tweets.

Response Object

A successful classification result looks like this:

{
    "cap": {
        "english": 0.8018818614025648,
        "universal": 0.5557322218336633
    },
    "display_scores": {
        "english": {
            "astroturf": 0.0,
            "fake_follower": 4.1,
            "financial": 1.5,
            "other": 4.7,
            "overall": 4.7,
            "self_declared": 3.2,
            "spammer": 2.8
        },
        "universal": {
            "astroturf": 0.3,
            "fake_follower": 3.2,
            "financial": 1.6,
            "other": 3.8,
            "overall": 3.8,
            "self_declared": 3.7,
            "spammer": 2.3
        }
    },
    "raw_scores": {
        "english": {
            "astroturf": 0.0,
            "fake_follower": 0.81,
            "financial": 0.3,
            "other": 0.94,
            "overall": 0.94,
            "self_declared": 0.63,
            "spammer": 0.57
        },
        "universal": {
            "astroturf": 0.06,
            "fake_follower": 0.64,
            "financial": 0.3133333333333333,
            "other": 0.76,
            "overall": 0.76,
            "self_declared": 0.74,
            "spammer": 0.47
        }
    },
    "user": {
        "majority_lang": "en",
        "user_data": {
            "id_str": "11330",
            "screen_name": "test_screen_name"
        }
    }
}

Meanings of the elements in the response:

• user: Twitter user object (from the request) plus the language inferred from the majority of tweets
• raw scores: bot scores in the [0,1] range, both English (using all features) and Universal (using only language-independent features); in each case we have the overall score and the sub-scores for each bot class (see below for subclass names and definitions)
• display scores: same as raw scores, but in the [0,5] range
• cap: Complete Automation Probability (CAP) is the conditional probability that accounts with a score equal to or greater than this are automated; based on inferred language

Bot types:

• fake_follower: bots purchased to increase follower counts
• self_declared: bots from botwiki.org
• astroturf: manually labeled political bots and accounts involved in follow trains that systematically delete content
• spammer: accounts labeled as spambots from several datasets
• financial: bots that post using cashtags
• other: miscellaneous other bots obtained from manual annotation, user feedback, etc.

BotometerLite

Overview

Endpoint: Check accounts in bulk (/litev1/check_accounts_in_bulk).

Reference: Yang, Kai-Cheng, Onur Varol, Pik-Mai Hui, and Filippo Menczer. “Scalable and generalizable social bot detection through data selection.” In Proceedings of the AAAI Conference on Artificial Intelligence, vol. 34, no. 01, pp. 1096-1103, 2020. DOI:10.1609/aaai.v34i01.5460

This endpoint offers the BotometerLite model. The endpoint flow works generally like this:

1. You use the Twitter Streaming, Search, or User lookup endpoints to obtain the tweets or user profiles from a set of accounts you want to analyze.
2. You POST the data to this endpoint in JSON format.
3. The API analyzes the accounts, scores them, and returns our results in JSON format.

Request Object

To analyze the accounts, POST the required data as JSON to the /litev1/check_accounts_in_bulk endpont. Your request must supply the x-rapidapi-key header as demonstrated below.

If you have a collection of tweets from Twitter, the request object looks roughly like this:

[tweet1, tweet2, ...]

where tweet1, tweet2, … are the tweet objects you collected from Twitter without modification.
The list should contain no more than 100 tweets.

If you only have a collection of user objects (i.e. you collected them using the Twitter user lookup endpoint), the request object should look like this:

[
    {
        "created_at": "Wed Jun 05 21:42:20 +0000 2019", 
        "user":  { 
                 "id": 1234,
                 "screen_name": "test_user_1",
                 "....": "...."
             }
    },
    {
        "created_at": "Wed Aug 04 21:42:20 +0000 2020", 
        "user":  { 
                 "id": 12345,
                 "screen_name": "test_user_2",
                 "....": "...."
             }
    },
    ....
]

Notes:

• The created_at field is required and should be the time stamp of when the user object was collected.
• The user object is required and should be the profile of a target account.
• The list should contain no more than 100 elements.

Response Object

[
    {"botscore": 0.65, "tweet_id": "235135",  "user_id": 1234},
    {"botscore": 0.29, "tweet_id": "235134", "user_id": 12345}
]

For each tweet posted to the API, a corresponding object with the user_id, tweet_id, and bot score will be returned unless some errors occurred.
Note that if you follow the second example above where only the user objects are posted, the tweet_ids in the response will be set to null.

Rate Limits

Botometer-V4

The Botometer-V4 endpoint is available in all plans.

• Our BASIC rate limit is set at 500 requests per day, per user. This plan is mainly for testing. If you desire a higher daily rate limit, faster response times, and/or the ability to exceed the daily rate limit, please subscribe to the PRO or ULTRA plans.
• The PRO has no subscription fee. You will, however, need to enter a valid credit card. It provides a rate limit of 2,000 requests per day, and you go beyond the rate limit for $1/1k requests.
• The ULTRA plan imposes a subscription fee of $50 per month. In return, it provides a rate limit of 17,280 requests per day, which reflects the Twitter Search API’s user-authenticated rate limit. The plan also enables users to exceed their daily quota for $1/1k requests. (Note that Twitter’s app-only authentication allows for a higher rate limit.)

Users are free to switch between the plans at will without having to change the endpoint in their code.

BotometerLite

The BotometerLite endpoint is only available through the ULTRA plan, which provides a rate limit of 200 requests per day and allows the users to exceed the quota for $1/100 requests.
Note that each request allows checking up to 100 accounts.

For answers to questions about the Botometer service in general, please refer to our website’s FAQ.

Using botometer-python

You can simplify the usage of the Botometer Pro API with our botometer-python client library.

To check higher volumes of accounts, you may also want to use app-only authentication with the Twitter API. For complete info, see this wiki page on our GitHub repo.

You can easily use the Pro API with our botometer-python client library by specifying botometer_api_url in the constructor:

botometer_api_url = 'https://botometer-pro.p.mashape.com'
bom = botometer.Botometer(botometer_api_url=botometer_api_url,
                          wait_on_ratelimit=True,
                          mashape_key=mashape_key,
                          **twitter_app_auth)

In order to make use of the higher ratelimits allowed with the paid tier of the Pro API, you probably also want to use app-only authentication for the Twitter API. For complete info, see this wiki page on our GitHub.