Usage API


Overview 

The Usage API returns data consumption information for a Gnip Customer Account. The Usage API is ideal for Gnip customers who need programmatic access to information related to their activity consumption across publishers and products. Note that the figures returned in the Usage API are the same as those that can be referenced on the Gnip Console.

Important Disclaimer

The usage counts returned from the Usage API may not match those on a billing invoice due to trials and other billing adjustments. All values represent usage by product and stream (i.e., PowerTrack and PowerTrack Replay are combined). All numbers are based on deduped activities consumed within a given day (in UTC).


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.

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.

GET:

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

https://account-api.gnip.com/accounts/[your_account_name]/usage.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 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 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'.

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: 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://account-api.gnip.com/accounts/[your_account_here]/usage.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"
										
status The status of the account for which usage data was requested. Status values can be 'active' or 'inactive'.

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

The unit of time for which usage data is provided.


"bucket": "month"
			
fromDate

The oldest UTC timestamp for which usage data is provided.


"fromDate": "201403010000"
			
toDate

The latest UTC timestamp for which usage data is provided.


"toDate": "201403050000"
			

publishers

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

Show Sub-Field Details

Element Description
name The name of the publisher.

"name": "Twitter"
										
type The type of the publisher.

"type": "twitter"
										
used An array of time periods that specify the number of activities used, fromDate, and toDate for each period.

"used": [
    {
      "activities": 21000,
      "fromDate": "201403010000",
      "toDate": "201403050000"
    }
]
										
projected A projection of activity usage through the end of the current month with corresponding fromDate and toDate for the projected period.

"projected": {
    "activities": 15000,
    "fromDate": "201403010000",
    "toDate": "201404010000"
}
										
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": [
    {
      "name": "Search API",
      "type": "search",
      "used": [
        {
          "activities": 1000,
          "fromDate": "201403010000",
          "toDate": "201403050000"
        }
      ],
      "projected": {
        "activities": 5000,
        "fromDate": "201403010000",
        "toDate": "201404010000"
      },
      "thresholds": [
        {
          "requests": 1000,
          "type": "cap"
        }
      ],
    },
    {
      "name": "PowerTrack",
      "type": "powertrack",
      "used": [
        {
          "activities": 20000,
          "fromDate": "201403010000",
          "toDate": "201403050000"
        }
      ],
      "projected": {
        "activities": 10000,
        "fromDate": "201403010000",
        "toDate": "201404010000"
      },
    }
]
										
thresholds An array of thresholds that are configured for this publisher. Each threshold is listed with the corresponding volume and type.

"thresholds": [
    {
      "activities": 10000,
      "type": "alert"
    },
    {
      "activities": 20000,
      "type": "alert"
    },
    {
      "activities": 25000,
      "type": "cap"
    }
]
										
"publishers": [
{
  "name": "Twitter",
  "used": [
    {
      "activities": 21000,
      "fromDate": "201403010000",
      "toDate": "201403050000"
    }
  ],
  "projected": {
    "activities": 15000,
    "fromDate": "201403010000",
    "toDate": "201404010000"
  },
  "products": [
    {
      "name": "Search API",
      "type": "search",
      "used": [
        {
          "activities": 1000,
          "fromDate": "201403010000",
          "toDate": "201403050000"
        }
      ],
      "projected": {
        "activities": 5000,
        "fromDate": "201403010000",
        "toDate": "201404010000"
      },
      "thresholds": [
        {
          "requests": 1000,
          "type": "cap"
        }
      ],
    },
    {
      "name": "PowerTrack",
      "type": "powertrack",
      "used": [
        {
          "activities": 20000,
          "fromDate": "201403010000",
          "toDate": "201403050000"
        }
      ],
      "projected": {
        "activities": 10000,
        "fromDate": "201403010000",
        "toDate": "201404010000"
      },
    }
  ],
  ,
  "thresholds": [
    {
      "activities": 10000,
      "type": "alert"
    },
    {
      "activities": 20000,
      "type": "alert"
    },
    {
      "activities": 25000,
      "type": "cap"
    }
  ],
}]
                        

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 processed and updated several times per hour consistently throughout the day.

The Usage API makes data available for a rolling window of the past 12 months. Any requests made with a fromDate that is more than 12 months in the past will not return usage data.

Rate Limit

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