This page is designed to help you migrate to the new Usage API 2.0. Below you’ll find an expanded list of new features and version differences to help with the transition.

Note: We will announce any changes to this API in the Change Log found on the Usage API 2.0 home page.

Summary of Changes 

  • New endpoint URL
  • Increased granularity with stream level usage data
  • Search Usage data (requests) is now broken out by Full Archive and 30 Day search products
  • Historical PowerTrack data is now broken out by Days and Jobs
  • The “account.status” field no longer exists in 2.0
  • Requests cannot be made with a “fromDate” or “toDate” older than December 1, 2015
  • Version 2.0 currently does not include the threshold data (critical, warning, and cap threshold volumes)

New Endpoint URL  

Below is the new endpoint for the Usage API 2.0:

https://gnip-api.twitter.com/metrics/usage/accounts/[account-name].json


New Features 

  • Stream level usage data: 2.0 introduces a new concept of “endpoint”, which provides usage data at the stream level, not just the product level
    • A product like PowerTrack can have several streams, so this allows you to view more granular usage data
  • The data fields within “publisher.used” are now more granular and descriptive:
    • Search ‘requests’ are now broken out by Full Archive and 30 Day search products (searchRequests30Day and searchRequestsFullArchive)
    • For Historical PowerTrack, the “publisher.used” is now broken out by HPT days and jobs (historicalPowertrackDays and historicalPowertrackJobs)
    • We have a “publisher.used.timePeriod” in 2.0 for each results entry where as in 1.0 we have publisher.used.from/toDate
"used": [
    {
      "activities": 11884,
      "searchRequests30Day": 0,
      "searchRequestsFullArchive": 0,
      "historicalPowertrackDays": 5,
      "historicalPowertrackJobs": 5,
      "timePeriod": "201511010000"
    },
  • Historical PowerTrack data is now broken out by Days and Jobs (see Sample Payload section)

Version Differences  

  • The “account.status” field no longer exists in 2.0
  • Usage data is now reported using the timePeriod structure for dates, rather than having a fromDate and toDate in the response
  • A request with no toDate will default to the next bucket (e.g., tomorrow for bucket=day)
  • A request with no fromDate and toDate will default to bucket=monthly, and show data for the current month plus the two immediately previous months
  • The fromDate and toDate parameters have to be rounded to a month boundary when bucket=month or a day boundary when bucket=day
    • Reminder: fromDate is inclusive, toDate is exclusive
  • Requests cannot be made with a fromDate or toDate older than December 1, 2015
  • Single requests cannot be made for a duration longer than 3 months
  • The “.name” in 1.0 is now “.type in 2.0”. What was the “.type” identifier in 1.0 is no longer available in 2.0, as it’s replaced by the name.
    • 1.0 - “name”: “Search API (Full-Archive)”, “type”: “fullarchive”
    • 2.0 - “type”: “Search API (Full-Archive)”
  • The projected field is not available if the current time is 0000-0059:
    • This is true on any day with Day buckets
    • This is true on the first day of the month with Month buckets
  • Version 2.0 currently does not include the threshold data (critical, warning, and cap threshold volumes)

Sample Payload 

Below is a sample of the new 2.0 payload:

{
  "account": {
    "name": "gnip-account-name"
  },
  "bucket": "month",
  "fromDate": "201601010000",
  "toDate": "201604010000",
  "publishers": [
    {
      "type": "automattic",
      "used": [
        {
          "activities": 0,
          "timePeriod": "201601010000"
        },
        {
          "activities": 0,
          "timePeriod": "201602010000"
        },
        {
          "activities": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 0
            },
            {
              "timePeriod": "201603010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "dev",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            }
          ]
        }
      ]
    },
    {
      "type": "foursquare",
      "used": [
        {
          "activities": 0,
          "timePeriod": "201601010000"
        },
        {
          "activities": 0,
          "timePeriod": "201602010000"
        },
        {
          "activities": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 0
            },
            {
              "timePeriod": "201603010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "dev",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            }
          ]
        }
      ]
    },
    {
      "type": "tumblr",
      "used": [
        {
          "activities": 0,
          "timePeriod": "201601010000"
        },
        {
          "activities": 0,
          "timePeriod": "201602010000"
        },
        {
          "activities": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 0,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 0
            },
            {
              "timePeriod": "201603010000",
              "activities": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "dev",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            }
          ]
        }
      ]
    },
    {
      "type": "twitter",
      "used": [
        {
          "activities": 0,
          "searchRequests30Day": 0,
          "searchRequestsFullArchive": 0,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0,
          "timePeriod": "201601010000"
        },
        {
          "activities": 9530,
          "searchRequests30Day": 64,
          "searchRequestsFullArchive": 24,
          "historicalPowertrackDays": 0,
          "historicalPowertrackJobs": 0,
          "timePeriod": "201602010000"
        },
        {
          "activities": 1759487,
          "searchRequests30Day": 10,
          "searchRequestsFullArchive": 3644,
          "historicalPowertrackDays": 63,
          "historicalPowertrackJobs": 2,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 1857872,
        "searchRequests30Day": 10,
        "searchRequestsFullArchive": 3939,
        "historicalPowertrackDays": 68,
        "historicalPowertrackJobs": 2,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "Historical PowerTrack Subscription",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 0,
              "days": 0,
              "jobs": 0
            },
            {
              "timePeriod": "201603010000",
              "activities": 41080,
              "days": 63,
              "jobs": 2
            }
          ]
        },
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 2360
            },
            {
              "timePeriod": "201603010000",
              "activities": 23205
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 25088
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "TestUserCountryModel",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack",
              "label": "longrules",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack",
              "label": "shortrules",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "v2",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 2360
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 23205
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 25088
              }
            }
          ]
        },
        {
          "type": "Search API",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 6915,
              "searchRequests30Day": 64
            },
            {
              "timePeriod": "201603010000",
              "activities": 8,
              "searchRequests30Day": 8
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 8,
            "searchRequests30Day": 8
          },
          "endpoints": [
            {
              "type": "Search API",
              "label": "prod",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 6915,
                  "searchRequests30Day": 64
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 8,
                  "searchRequests30Day": 8
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 8,
                "searchRequests30Day": 8
              }
            }
          ]
        },
        {
          "type": "Search API (30-Day) 2.0",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 0,
              "searchRequests30Day": 0
            },
            {
              "timePeriod": "201603010000",
              "activities": 14,
              "searchRequests30Day": 2
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 15,
            "searchRequests30Day": 2
          },
          "endpoints": [
            {
              "type": "Search API (30-Day) 2.0",
              "label": "prod",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 14,
                  "searchRequests30Day": 2
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 15,
                "searchRequests30Day": 2
              }
            }
          ]
        },
        {
          "type": "Search API (Full-Archive)",
          "used": [
            {
              "timePeriod": "201601010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            },
            {
              "timePeriod": "201602010000",
              "activities": 2576,
              "searchRequestsFullArchive": 24
            },
            {
              "timePeriod": "201603010000",
              "activities": 1695178,
              "searchRequestsFullArchive": 3644
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 1832758,
            "searchRequestsFullArchive": 3939
          },
          "endpoints": [
            {
              "type": "Search API (Full-Archive)",
              "label": "UsedForDiscovery2",
              "used": [
                {
                  "timePeriod": "201601010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                },
                {
                  "timePeriod": "201602010000",
                  "activities": 2576,
                  "searchRequestsFullArchive": 24
                },
                {
                  "timePeriod": "201603010000",
                  "activities": 1695178,
                  "searchRequestsFullArchive": 3644
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 1832758,
                "searchRequestsFullArchive": 3939
              }
            }
          ]
        }
      ]
    }
  ],
}