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.


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. The oldest UTC timestamp from which the usage data will be provided. Timestamp is in day granularity and is inclusive (i.e., 201403010000 includes the 0301 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.

Example: 201403010000 will return data starting March 1st, 2014 onward, including March 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., 201403020000 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=monthly, and show data for the current month plus the two immediately previous months.

Example: 201403050000 will return data to March 5, 2014, not including any data from March 5th.



Example GET Request

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

curl -u[username] "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.

account

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

Show Sub-Field Details

Element Description
name The name of the account for which usage data was requested.

"name": "your-account-name"
										
"account": {
	"name": "your-account-name",
}
						
bucket

The unit of time for which usage data is provided.


"bucket": "month"
			
fromDate

The oldest UTC timestamp for which usage data is provided (inclusive).


"fromDate": "201603010000"
			
toDate

The latest UTC timestamp for which usage data is provided (exclusive).


"toDate": "201603050000"
			

publishers

An array of publishers that have active products for the account for the time period requested.

Show Sub-Field Details

Element Description
type The type of the publisher.

"type": "twitter"
										
used An array of time periods that specify the number of activities used, requests made, and the corresponding time period.

"used": [
    {
      "activities": 84,
      "searchRequests30Day": 4,
      "searchRequestsFullArchive": 0,
      "timePeriod": "201603010000"
    }
  ],
										
projected A projection of activity usage through the end of the current month with corresponding time period.

"projected": {
    "activities": 93,
    "searchRequests30Day": 4,
    "searchRequestsFullArchive": 0,
    "timePeriod": "201603010000"
  },
										
products An array of products that are active for this publisher. Each product contains information for type, used, projected, and thresholds for this product.

"products": [
	{
	  "type": "PowerTrack",
	  "used": [
	    {
	      "timePeriod": "201603010000",
	      "activities": 23
	    }
	  ],
	  "projected": {
	    "timePeriod": "201603010000",
	    "activities": 25
	  },
	  "endpoints": [
	    {
	      "type": "PowerTrack",
	      "label": "prod",
	      "used": [
	        {
	          "timePeriod": "201603010000",
	          "activities": 0
	        }
	      ],
	      "projected": {
	        "timePeriod": "201603010000",
	        "activities": 0
	      }
	    },
	    {
	      "type": "PowerTrack2.0",
	      "label": "prod",
	      "used": [
	        {
	          "timePeriod": "201603010000",
	          "activities": 23
	        }
	      ],
	      "projected": {
	        "timePeriod": "201603010000",
	        "activities": 25
	      }
	    }
	  ]
	},
	{
	  "type": "SearchAPI",
	  "used": [
	    {
	      "timePeriod": "201603010000",
	      "activities": 49,
	      "searchRequests30Day": 4
	    }
	  ],
	  "projected": {
	    "timePeriod": "201603010000",
	    "activities": 54,
	    "searchRequests30Day": 4
	  },
	  "endpoints": [
	    {
	      "type": "SearchAPI",
	      "label": "prod",
	      "used": [
	        {
	          "timePeriod": "201603010000",
	          "activities": 49,
	          "searchRequests30Day": 4
	        }
	      ],
	      "projected": {
	        "timePeriod": "201603010000",
	        "activities": 54,
	        "searchRequests30Day": 4
	      }
	    }
	  ]
	},
	{
	  "type": "SearchAPI(30-Day)2.0",
	  "used": [
	    {
	      "timePeriod": "201603010000",
	      "activities": 0,
	      "searchRequests30Day": 0
	    }
	  ],
	  "projected": {
	    "timePeriod": "201603010000",
	    "activities": 0,
	    "searchRequests30Day": 0
	  },
	  "endpoints": [
	    {
	      "type": "SearchAPI(30-Day)2.0",
	      "label": "prod",
	      "used": [
	        {
	          "timePeriod": "201603010000",
	          "activities": 0,
	          "searchRequests30Day": 0
	        }
	      ],
	      "projected": {
	        "timePeriod": "201603010000",
	        "activities": 0,
	        "searchRequests30Day": 0
	      }
	    }
	  ]
	},
	{
	  "type": "SearchAPI(Full-Archive)",
	  "used": [
	    {
	      "timePeriod": "201603010000",
	      "activities": 0,
	      "searchRequestsFullArchive": 0
	    }
	  ],
	  "projected": {
	    "timePeriod": "201603010000",
	    "activities": 0,
	    "searchRequestsFullArchive": 0
	  },
	  "endpoints": [
	    {
	      "type": "SearchAPI(Full-Archive)",
	      "label": "dev",
	      "used": [
	        {
	          "timePeriod": "201603010000",
	          "activities": 0,
	          "searchRequestsFullArchive": 0
	        }
	      ],
	      "projected": {
	        "timePeriod": "201603010000",
	        "activities": 0,
	        "searchRequestsFullArchive": 0
	      }
	    }
	  ]
	}
	]
										
},
  "publishers": [
    {
      "type": "twitter",
      "used": [
        {
          "activities": 84,
          "searchRequests30Day": 4,
          "searchRequestsFullArchive": 0,
          "timePeriod": "201603010000"
        }
      ],
      "projected": {
        "activities": 93,
        "searchRequests30Day": 4,
        "searchRequestsFullArchive": 0,
        "timePeriod": "201603010000"
      },
      "products": [
        {
          "type": "PowerTrack",
          "used": [
            {
              "timePeriod": "201603010000",
              "activities": 23
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 25
          },
          "endpoints": [
            {
              "type": "PowerTrack",
              "label": "prod",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0
              }
            },
            {
              "type": "PowerTrack 2.0",
              "label": "v2",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 23
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 25
              }
            }
          ]
        },
        {
          "type": "Search API",
          "used": [
            {
              "timePeriod": "201603010000",
              "activities": 49,
              "searchRequests30Day": 4
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 54,
            "searchRequests30Day": 4
          },
          "endpoints": [
            {
              "type": "Search API",
              "label": "prod",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 49,
                  "searchRequests30Day": 4
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 54,
                "searchRequests30Day": 4
              }
            }
          ]
        },
        {
          "type": "Search API (30-Day) 2.0",
          "used": [
            {
              "timePeriod": "201603010000",
              "activities": 0,
              "searchRequests30Day": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0,
            "searchRequests30Day": 0
          },
          "endpoints": [
            {
              "type": "Search API (30-Day) 2.0",
              "label": "prod",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 0,
                  "searchRequests30Day": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0,
                "searchRequests30Day": 0
              }
            }
          ]
        },
        {
          "type": "Search API (Full-Archive)",
          "used": [
            {
              "timePeriod": "201603010000",
              "activities": 0,
              "searchRequestsFullArchive": 0
            }
          ],
          "projected": {
            "timePeriod": "201603010000",
            "activities": 0,
            "searchRequestsFullArchive": 0
          },
          "endpoints": [
            {
              "type": "Search API (Full-Archive)",
              "label": "dev",
              "used": [
                {
                  "timePeriod": "201603010000",
                  "activities": 0,
                  "searchRequestsFullArchive": 0
                }
              ],
              "projected": {
                "timePeriod": "201603010000",
                "activities": 0,
                "searchRequestsFullArchive": 0
              }
            }
          ]
        }
      ]
    }
  ],
                        

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.

Important Note: Usage API does not support requests with a “fromDate” or “toDate” older than December 1, 2015.