GET /account/usage

Retrieve usage data for a specified time period for the streaming platform, including overage and per interaction costs.

An HTTPS GET request sent to:

https://api.datasift.com/v1.3/account/usage

A successful call to this endpoint returns: 200 OK plus a JSON object.

Parameters

Parameter Description
period
optional

Allows you to specify a hourly, daily, or monthly aggregations for your
report.

For example, if you choose daily aggregation you will receive one set of
usage data for each day.

Default: hourly

start
optional

Optional start timestamp for your usage report.

If you omit the start time, DataSift uses one unit of the period (one hour,
one day, or one month). For example, if the period is daily you are
requesting a report based on the 24 hours that ended at the timestamp
specified in the end parameter.

Time ranges are treated as inclusive on the start and exclusive on the
end. That is, the exact second specified in the end parameter is excluded
from the range.

Note: we recommend that you choose a timestamp that falls exactly on
the hour/day/month start.

end
optional

Optional end timestamp for your usage report.

Time ranges are treated as inclusive on the start and exclusive on the
end. That is, the exact second specified in the end parameter is excluded
from the range.

Note: we recommend that you choose a timestamp that falls exactly on
the hour/day/month end.

Default: now

Examples

  1. Retrieve usage details for the current hour:

    curl -X GET https://api.datasift.com/v1.3/account/usage?period=hourly \
      -H 'Authorization: username:api_key'

  2. Retrieve usage details for a specific day. We recommend that the start and end timestamps correspond exactly to the start and end of that day; for example: Sept 15, 2015 00:00:00 to Sept 16, 2015 00:00:00:

    curl -X GET https://api.datasift.com/v1.3/account/usage?period=daily&start=1442275200&end=1442361600 \
      -H 'Authorization: username:api_key'

  3. Retrieve usage details for one month; for example: the month of September 2015 begins at Sept 1, 2015 00:00:00 and ends at Oct 1, 2015 00:00:00:

    curl -X GET https://api.datasift.com/v1.3/account/usage?period=monthly&start=1441065600&end=1443657600 \
      -H 'Authorization: username:api_key'

Understanding start and end timestamps

In nearly all cases you'll find it best to specify both the start and the end parameters, and to pick timestamps that are exactly on the hour.

For example, if you choose your period to be hourly and you set your start parameter to be the timestamp for 13:00 and your end parameter to be the timestamp for 14:00, you will receive usage details for 13:00:00-13:59:59.

  • If you choose your start parameter to be the timestamp for 13:30 and your end parameter to be the timestamp for 14:20, DataSift will automatically round both of those times up to the next hour (14:00 and 15:00) so you will receive usage details for 14:00:00-14:59:59.
  • Beware: if you choose your start parameter to be the timestamp for 13:10 and your end parameter to be the timestamp for 13:50, DataSift will automatically round both of those times up to the next hour (14:00 and, again, 14:00) so you will receive nothing.
  • If you omit the start parameter and specify the end, DataSift will give you data for the past hour/day/month, depending on the period you specified.
  • If you omit the end parameter and specify the start, the end defaults to now.
  • If you request usage data for the current hour/day/month and that period has not yet ended, you will receive all the data that is currently available for the period.

Output

The output is an array of elements covering the usage for the period you requested. The array might be large; for example, it will be large if you set your end timestamp to be 10 days after your start timestamp and choose period=hourly.

Output Fields

Property Type Description
quantity string The number of units you have used in the period you specified.
cost string The cost in US dollars. Typically it is zero because your plan includes a usage allowance. However, it will be greater than zero if you go into overage for DPUs or data volume plans. For data sources charged per interaction this element will represent the licensing cost for that data source.
category string

Indicates the DataSift service that you used:

Value Description
realtime One of the streaming sources or augmentations.
historics The Historics service.
historicspreview The Historics Preview.
managed_sources One of the Managed Sources.
unit string

Indicates the type of billing involved. The units apply to the quantity field:

Value Description
dpu DPUs (used on the streaming platform).
interaction Individual JSON interactions.

For example, if unit is dpu and quantity is 10, that represents 10 DPUs.

source string This element is populated when unit=interaction. It indicates the data source or augmentation.
timestamp int Timestamp that indicates the start of the period that the usage data covers. For example, if you set your period to be hourly and you choose a three-hour window, you will receive an array of data; the individual objects in the array will each have timestamps to indicate whether they cover the first, second, or third hour.

Responses

Response code Description
Status 200 OK The call was successful
Status 400 Bad Request

Occurs if any of the parameters are invalid or malformed.

{
    "error": "start must be earlier than the end"
}
{
    "error": "start must be a valid integer"
}
{
    "error": "end must be a valid integer"
}
{
    "error": "start must be less than or equal to current time"
}
{
    "error": "end must be less than or equal to current time"
}
{
    "error": "period is invalid; valid values are: hourly,daily,monthly""
}

Notes

  1. All calls to the API must be properly authenticated with a DataSift username and API key.
  2. All calls to the API must be versioned. The current version is v1.3.
  3. This endpoint cannot supply streaming usage data prior to 2015-10-01 00:00:00.
  4. Data Sources which are not charged per interaction are not included in the response from this endpoint. This includes all Managed Sources.

Resource information

Rate limit cost: 5

Requires authentication: Yes

Response formats: JSON, JSONP