The Fastly Historical Stats API (i.e., the Stats API) is a RESTful API that allows Fastly customers to query historical caching stats such as number of requests, hit ratio, and number of errors. The Stats API provides an advanced querying interface that allows for fine grained time period, regional, and sampling control. This document provides a basic overview of Stats and documents all available endpoints.

Endpoint

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

Authentication

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:

Yesterday

Two weeks ago

2/20/2013

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

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:

from <= recorded < to

NOTE: We store historical stats information using UTC, and not local time zones. This means that we will use the UTC interpretations of your inputs when querying stats information.

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:

minute - Stats will be sampled by minute for each recorded minute in the specified window

hour - Sample by hour within the specified window

day - Sample by day within the specified window

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:

1 day = 24 hours

1 hour = 60 minutes

1 day = 60 * 24 = 1,440 minutes

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:

usa - Restricts the query to statistics reported by POPs in the continental United States

europe - Restricts the query to statistics reported by POPs in Europe

anzac - Restricts the query to statistics reported by POPs in Australia and New Zealand

asia - Restricts the query to statistics reported by POPs in Asia

latam - Restricts the query to statistics reported by POPs in Latin America

south_africa - Restricts the query to statistics reported by POPs in southern Africa

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:

status - Whether or not we were able to successfully execute the query

meta - Meta information about the scope of the query in a human readable format

msg - If the query was not successful this will provide a string that explains why

data - This contains the actual results of the query that we processed

Availability of Data

The collection and processing of statistics information from a globally distributed CDN, such as Fastly, is not instantaneous. Thus there will be a notable delay as to when certain sampling range information will be up to date. Here are the general guidelines:

Minutely data will be delayed by roughly 10 to 15 minutes from the current time

Hourly data will be delayed by the same amount, and the current hour will return a partial result (because the hour has not finished but we are incrementally aggregating data)

Daily data works similarly to hourly data and the current day will also represent a partial result

API Reference

Historical Stats

The Fastly Historical Stats API is a RESTful API that allows Fastly customers to query historical caching stats such as number of requests, hit ratio, and number of errors.

GET
/stats/usage_by_month

Returns month-to-date usage details for a given month and year. Usage details are aggregated by service and across all Fastly services, and then grouped by region. This endpoint does not use the from or to fields for selecting the date for which data is requested. Instead, it uses month and year integer fields. Both fields are optional and default to the current month and year respectively. When set, an optional billable_units field will convert bandwidth to GB and divide requests by 10,000.