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.
The stats API is accessible from
https://api.fastly.com/stats/*, and can be used with both Fastly Key and Username / Password authentication. Authentication works exactly as it does for the Core Fastly API, please refer to Authentication Documentation for further details.
Here is an example using the command-line tool CURL:
curl -H "Fastly-Key: YOUR_API_KEY" https://api.fastly.com/stats/usage
To find your API key please visit the "Account" section in the Fastly Application. Your organization's API key should be displayed at the top left of the page under the heading "API Key". If the API key does not appear, then you may not be authorized to view the key and you should ask the person within your organization that setup the Fastly account. If all else fails you can contact support and ask to receive your API key.
There are four query parameters that you can use to specify what information is returned by the stats API. The
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.
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:
It is important to note that 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.
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
from parameters if you omit them:
Each value for the
by parameter has associated defaults for the
from parameters if they are omitted, here's an overview:
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
from parameters. We will not process exceedingly large queries. Please refer to the Response Format section below for more details.
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:
The list of regions will always contain the ones listed above but may grow as Fastly expands into new parts of the globe. Because the list is dynamic, please use the following endpoint to get a list of all available regions:
It is important to note that not all regions are available to all customers at this time. If you need support for a particular region please feel free to contact us via our helpdesk.
We collect many different stats fields when processing your requests. Some of the stats endpoints detailed below allow you to specify particular fields. These are the major fields we support:
The following fields may or may not be available depending on the nature of your services:
We also provide specialized HTTP response code tally fields:
For more information on HTTP status code meanings, please refer to "List of HTTP status codes" @ Wikipedia. Important Note: that we have added various fields over time. If you are a long time fastly user some of the fields you request may not be accurate.
To make it easier to understand how a query is being processed we use a specific JSON response format. Here is an example:
Each of the fields denotes the following: >
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:
Certain queries can take a good deal of time to process with the stats API. Depending on the query parameters different rate limiting is applied to a single key or username/password. All queries that would result in greater than 2800 records are not processed and will return an error.
Queries over time windows that occur strictly in the past (i.e. aggregation has been completed and the values will no longer change in the database) can be queried at will. Since different sampling rates aggregate over different periods, changing the
by parameter of your query can affect whether or not the query can be made at will.
In general, requests to the Stats API are not rate-limited under the following conditions:
by=minuteis set and
tois set to a time that is at least 30 minutes behind the current time
by=houris set and
tois set to a time that is at least 1 hour and 30 minutes behind the current time
by=dayis set and
tois set to a time at least 1 day behind the current time
Requests that are not exempt from rate limiting are limited based on the result size of the request. Here are the rules we use when rate limiting:
These limits are subject to change and will be updated as time passes.
When a request is rate limited it will be clearly denoted in the
msg fields of the response. For more information about response formats see the Response Format section above.
Fetches historical stats for each of your fastly services and groups the results by service id.
Fetches the specified field from the historical stats for each of your services and groups the results by service id.
Fetches historical stats information aggregated across all of your Fastly services.
Fetches historical stats for a given service.
Fetches the specified field from the historical stats for a given service.
Returns usage information aggregated across all Fastly services and grouped by region.
Returns usage information aggregated by service and grouped by service & region.
Fetches the list of codes for regions that are covered by the Fastly CDN service.