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 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.
Here's an example using the command-line tool cURL:
curl -H "Fastly-Key: YOUR_API_KEY" https://api.fastly.com/stats/usage
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
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:
Two weeks ago
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:
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
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:
- 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
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:
usa- Restricts the query to statistics reported by continental United States POPs (Points of Presence)
europe- Restricts the query to statistics reported by European POPs
anzac- Restricts the query to Australia / New Zealand / Asia / Pacific POPs
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.
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:
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
|requests||integer||Number of requests processed|
|hits||integer||Number of cache hits|
|hits_time||float||Amount of time spent processing cache hits (in seconds)|
|miss||integer||Number of cache misses|
|miss_time||float||Amount of time spent processing cache misses (in seconds)|
|pass||integer||Number of requests that passed through the CDN without being cached|
|errors||integer||Number of cache errors|
|hit_ratio||float||Ratio of cache hits to cache misses (between 0 and 1)|
|bandwidth||integer||Total bytes delivered (body_size + header_size)|
|body_size||integer||Total body bytes delivered|
|header_size||integer||Total header bytes delivered|
|uncacheable||integer||Number of requests that were denoted uncachable.|
|pipe||integer||Optional. Pipe operations performed (legacy feature)|
|status_200||integer||Number of responses sent with status code 200 (Success)|
|status_204||integer||Number of responses sent with status code 204 (No Content)|
|status_301||integer||Number of responses sent with status code 301 (Moved Permanently)|
|status_302||integer||Number of responses sent with status code 302 (Found)|
|status_304||integer||Number of responses sent with status code 304 (Not Modified)|
|status_503||integer||Number of responses sent with status code 503 (Service Unavailable)|
|status_1xx||integer||Number of "Informational" category status codes delivered|
|status_2xx||integer||"Success" status codes delivered|
|status_3xx||integer||"Redirection" codes delivered|
|status_4xx||integer||"Client Error" codes delivered|
|status_5xx||integer||"Server Error" codes delivered|
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.