By OSoMe
Updated a year ago
Botometer Overview
Botometer (formerly Truthy BotOrNot) checks the activity of a Twitter account and gives it a score based on how likely the account is to be a bot. Higher scores are more bot-like.
Followers on API
Follow this API
resourcesProvider WebsiteTerms of Service
More Details

Botometer API Overview

The API 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 us the Twitter data via JSON.
  3. We analyze it, score it, and return our classification results as JSON.

Response Object

A successful classification result looks like this:

  "cap": {
    "english": 0.12,
    "universal": 0.11
  "scores": {
    "english": 0.34,
    "universal": 0.36
  "display_scores": {
    "english": 1.7,
    "universal": 2.0,
    "friend": 2.3,
    "sentiment": 1.7,
    "temporal": 2.8,
    "user": 1.5,
    "network": 2.2,
    "content": 2.1
  "categories": {
    "friend": 0.45,
    "sentiment": 0.34,
    "temporal": 0.55,
    "user": 0.29,
    "network": 0.43,
    "content": 0.41
  "user": {
    "screen_name": "Botometer",
    "id": "2451308594"

The response object has five main pieces:

  • User is exactly the user object from the request. We return this to you untouched with asynchronous workflows in mind, so that you don't have to worry about keeping the user data and matching it up to the appropriate response later.
  • Scores contains the overall classification results. The english score uses all six categories of features, while the universal score omits sentiment and content features, both of which are English-specific.
  • Categories gives subscores for each of the six feature classes.
  • CAP Complete Automation Probability (CAP) is the probability, according to our models, that this account is completely automated, i.e., a bot. This probability calculation uses Bayes' theorem to take into account an estimate of the overall prevalence of bots, so as to balance false positives with false negatives.
  • Display_scores are bascially the corresponding original scores multiplied by 5. Display scores are shown on .

Request Object

In order to analyze an account, POST the required Twitter data as JSON to the check_account endpont. Your request must supply the X-Mashape-Key header as demonstrated in the API documentation.

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": "@TruthyAtIndiana is also cool!",
      "...": "..."

This object has three main parts:

  • User is derived from Twitter's GET users/show REST endpoint. 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 by Twitter's GET statuses/user_timeline endpoint. Make sure to include the count=200 and include_rts=true parameter 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 the statuses property of the Search API response. This is an array of Tweet objects. Note that your Twitter API search should contain [email protected] in order to search for retweets and mentions of the user in question, and also the count=100 parameter 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.

Notes on migrating from API v1

Migrating from our older API v1 is fairly simple. Here are some notes about the process.

  • All of the Twitter-facing parts of your workflow should be the same. API v2 ingests the same basic data as before.
  • The request object:
    • The search results and user timeline are no longer concatenated together into content. This is so we can provide better error messages and feedback.
    • The meta property has been more-accurately named user.
    • You must now use the Mashape endpoint and include the X-Mashape-Key header.
  • The response object:
    • Instead of score being a single float, we provide a scores object with evaluations from multiple classifiers.

Rate Limit

Our rate limit is set at 2,000 requests per day, per user. If you desire a higher daily ratelimit and/or the ability to exceed the daily ratelimit, please see our Botometer Pro API. Do note that the basic tier of the Pro API does provide a significantly higher ratelimit without a monthly fee.

Have a question about this API?Ask the API Provider.
More by OSoMe
Developers who viewed Botometer also viewed

Install SDK for (Node.js)Unirest

OAuth2 Authentication
Client ID
Client Secret
OAuth2 Authentication