Historical Stats

The Fastly historical Stats API allows you to programmatically retrieve historical caching statistics derived from your Fastly services. You can use these metrics to help you optimize your site’s data caching and analyze your site’s traffic.

Endpoint

The base endpoint for the Stats API is https://api.fastly.com/. All URLs are relative to that endpoint. All requests must be sent over HTTPS.

Authentication

To authenticate, use a Fastly-Key header containing your API token.

Here's an example using the command-line tool cURL:

1
curl -H "Fastly-Key: YOUR_FASTLY_TOKEN" https://api.fastly.com/stats

Availability of Data

As a general rule, minutely, hourly, and daily data will each be delayed by approximately 10 to 15 minutes from the current time due to the time it takes to collect and process historical data. In addition, the current hour and current day will only return partial results because the data is still being incrementally aggregated for that time period, which isn’t complete.

Query Options (Time Range, Sampling Rate, and Regions)

There are four query parameters that you can use to specify what information is returned by the stats API. The from and to parameters control the window over which you want to fetch stats information. The by controls the sampling rate (day, hour, or minute). And the region parameter allows you to restrict the result set to a particular region.

Param: from and to

The from and to parameters are exact times that control the window over which to fetch historical statistics. By default you can use Unix timestamps when specifying these parameters, but many forms of human readable inputs are also available, such as:

Date parsing is performed using the Chronic ruby library; for the most detailed information on exactly what formats are available please visit the gem's GitHub page (https://github.com/mojombo/chronic).

Let's see some examples:

/stats?from=10+days+ago
Returns stats for each of your services, by day, for the last ten days
/stats?from=1494793777&to=1494966577
Stats from Tuesday 14th May 2017 @ 20:29:37 UTC to Thursday 16th May 2017 @ 20:29:37 UTC
/stats?from=1%2F1%2F2017&to=2%2F1%2F2017
Daily stats from January 1st, 2017 (1/1/2017) to February 1st, 2017 (2/1/2017)

When the time of day is not specified, the Stats API assumes 12pm. To specify a midnight to midnight range, you would use from=1%2F1%2F2013%2000:00&to=2%2F1%2F2013%2000:00/ (from=1/1/2013 00:00&to=2/1/2013 00:00, before encoding).

The from parameter is "inclusive" and the to parameter is "exclusive". This means that we will return only rows with recorded times that match the following inequality:

1
from <= recorded < to

Param: by

The by parameter allows you to control the sampling rate used to produce the result set from querying the Stats API. There are three values that can be set:

If you do not provide a by parameter in your query it will default to 'day'. Each sampling rate also specifies default to and from parameters if you omit them:

Each value for the by parameter has associated defaults for the to and from parameters if they are omitted, here's an overview:

/stats
Defaults to: By day, from 1 month ago, to now
/stats?by=hour
Defaults to: by hour, from 1 day ago, to now
/stats?by=minute
Defaults to: by minute, from 30 minutes ago, to now

It is important to remember the following conversions when performing queries:

When changing the sampling rate via the by parameter you can accidentally ask for very large data sets if you have defined to and from parameters. We will not process exceedingly large queries. Please refer to the Response Format section below for more details.

Param: region

The Stats API also allows you to limit the scope of your query by restricting it to a particular region. This is achieved via the use of the region parameter. Currently the following regions are supported:

Usage is exceedingly simple, let's look at some examples:

/stats
Returns stats for all regions
/stats?region=usa
Returns stats for only US POPs
/stats?region=europe
Returns stats for European POPs only

The following endpoint provides a complete list of all available regions:

GET /stats/regions
See the API section below for example output

Response Format

To make it easier to understand how a query is being processed we use a specific JSON response format. Here is an example:

/stats?from=1+day+ago
{
"status": "success",
"meta": {
"to": "Thu May 16 20:08:35 UTC 2013",
"from": "Wed May 15 20:08:35 UTC 2013",
"by": "day",
"region": "all"
},
"msg": null,
"data": [ ... ]
}

Each of the fields denotes the following:

API Reference