get-usage
get-usage

Methods 

Method Description
GET /metrics/usage/accounts/{ACCOUNT_NAME}.json Retrieve usage data

Where:

  • :account_name is the (case-sensitive) name associated with your account, as displayed at console.gnip.com

Authentication and Rate Limit 

Authentication

All requests to the Usage API require HTTP Basic Authentication, using any of the email/password credentials enabled on your account to log into your account at console.gnip.com or connect to any Gnip stream.

Rate Limit

The Usage API enforces a rate limit of two requests per minute.

Best Practices & Limitations 

Data Availability

Usage data is based on deduped activities consumed through the last full time period (UTC) that data was processed. Data is generally processed and updated up to the minute, except in cases where Gnip is deploying systems.

  • The Usage API allows you to access usage data since May 1, 2018.  After July 1, 2019 Usage API allows you to access usage data for the trailing 13 calendar months
  • You have the ability to access usage data in three month intervals defined with a fromDate and toDate

Requesting and Receiving Data 

The Usage API works by issuing an HTTP GET request with HTTP BASIC-AUTH credentials to the API endpoint for your account.

GET Request:

Make a GET request to the following endpoint with your user credentials and account name:

https://gnip-api.twitter.com/metrics/usage/accounts/:account_name.json

Additional Parameters
bucket Optional. The unit of time for which usage data will be provided. Usage data can be returned with daily or monthly granularity.

Requests made without a specified bucket will return monthly granularity.

Options: 'month' or 'day'
fromDate (YYYYMMDDHHMM) Optional. Usage data is only available starting from May 1, 2018. The oldest UTC timestamp from which the usage data will be provided. Timestamp is in day granularity and is inclusive (i.e., 201805010000 includes the 0501 day). Requests that contain values other than '0000' for hour and minute granularity will be defaulted to '0000'.

Requests made without a fromDate or toDate will return usage data by month for the current month and include a historical reference for the past two months.

Please note: Starting June 1, 2019, you can access the past 13 calendar months of usage data. For example, if it was the 10th of October, you can access usage data back to September 1st of the previous year.
Example: 201810010000 will return data starting October 1st, 2018 onward, including October 1st.
toDate (YYYYMMDDHHMM) Optional. The latest UTC timestamp to which the usage data will be provided. Timestamp is in day granularity and is not inclusive (i.e., 201703020000 does not include data for the 0302 day). When a toDate is specified for either the current day or a day in the future, usage data will be returned up to the last full day (UTC). Requests that contain values other than '0000' for hour and minute granularity will be defaulted to '0000'.

A request with no toDate, will default to the next bucket (tomorrow for bucket=day and next month for bucket=month). A request made with no fromDate and toDate will default to bucket=month, and show data for the current month plus the two immediately previous months.

Example: 201703050000 will return data to March 5, 2017, not including any data from March 5th.

Example GET Request

This request will return data by month granularity from March 1, 2017 to March 5, 2017, not including any data from March 5, 2017.

curl -u "https://gnip-api.twitter.com/metrics/usage/accounts/:account_name.json?bucket=month&fromdate=201403010000&toDate=201403150000"

Data Format 

The following tables describe the root-level data structures for usage data returned from the Usage API. For fields with multiple levels of sub-fields, click the links provided to reveal details about the sub-fields.

If you would like to see an sample of a full Usage API payload, please visit this page.

account

An object representing the account for which usage data was requested.

bucket

The unit of time for which usage data is provided. Can be either 'day' or 'month'.

fromDate

The earliest UTC timestamp for which you want to pull usage data (inclusive).

toDate

The latest UTC timestamp for which you want to pull usage data (exclusive).

publishers

Includes three primary objects: Used, projected, and products.