LOG IN SIGN UP
Documentation

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/. 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:

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

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:

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:

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:

  1. Minutely data will be delayed by roughly 10 to 15 minutes from the current time
  2. 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)
  3. 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.

Fields

field type description
requests integer

Number of requests processed.

hits integer

Number of cache hits.

hits_time float

Total 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.

pass_time float

Amount of time spent processing cache passes (in seconds).

errors integer

Number of cache errors.

restarts integer

Number of restarts performed.

hit_ratio float

Ratio of cache hits to cache misses (between 0 and 1).

bandwidth integer

Total bytes delivered (resp_header_bytes + resp_body_bytes + bereq_header_bytes + bereq_body_bytes).

body_size integer

Total body bytes delivered (alias for resp_body_bytes).

header_size integer

Total header bytes delivered (alias for resp_header_bytes).

req_body_bytes integer

Total body bytes received.

req_header_bytes integer

Total header bytes received.

resp_body_bytes integer

Total body bytes delivered.

resp_header_bytes integer

Total header bytes delivered.

bereq_body_bytes integer

Total body bytes sent to origin.

bereq_header_bytes integer

Total header bytes sent to origin.

uncacheable integer

Number of requests that were designated uncachable.

pipe integer

Optional. Pipe operations performed (legacy feature).

tls integer

Number of requests that were received over TLS.

tls_v10 integer

Number of requests received over TLS 1.0.

tls_v11 integer

Number of requests received over TLS 1.1.

tls_v12 integer

Number of requests received over TLS 1.2.

tls_v13 integer

Number of requests received over TLS 1.3

shield integer

Number of requests from shield to origin.

shield_resp_body_bytes integer

Total body bytes delivered via a shield.

shield_resp_header_bytes integer

Total header bytes delivered via a shield.

ipv6 integer

Number of requests that were received over IPv6.

otfp integer

Number of responses that came from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.

otfp_resp_body_bytes integer

Total body bytes delivered from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.

otfp_resp_header_bytes integer

Total header bytes delivered from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.

otfp_shield_resp_body_bytes integer

Total body bytes delivered via a shield for the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.

otfp_shield_resp_header_bytes integer

Total header bytes delivered via a shield for the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.

otfp_manifests integer

Number of responses that were manifest files from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.

otfp_deliver_time float

Total amount of time spent delivering a response from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand (in seconds).

otfp_shield_time float

Total amount of time spent delivering a response via a sheild from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand (in seconds).

video integer

Number of responses with the video segment or video manifest MIME type (i.e., application/x-mpegurl, application/vnd.apple.mpegurl, application/f4m, application/dash+xml, application/vnd.ms-sstr+xml, ideo/mp2t, audio/aac, video/f4f, video/x-flv, video/mp4, audio/mp4).

pci integer

Number of responses with the PCI flag turned on.

log integer

Number of log lines sent.

http2 integer

Number of requests received over HTTP2.

waf_logged integer

Number of requests that triggered a WAF rule and were logged.

waf_blocked integer

Number of requests that triggered a WAF rule and were blocked.

waf_passed integer

Number of requests that triggered a WAF rule and were passed.

attack_req_body_bytes integer

Total body bytes received from requests that triggered a WAF rule.

attack_req_header_bytes integer

Total header bytes received from requests that triggered a WAF rule.

attack_logged_req_body_bytes integer

Total body bytes received from requests that triggered a WAF rule that was logged.

attack_logged_req_header_bytes integer

Total header bytes received from requests that triggered a WAF rule that was logged.

attack_blocked_req_body_bytes integer

Total body bytes received from requests that triggered a WAF rule that was blocked.

attack_blocked_req_header_bytes integer

Total header bytes received from requests that triggered a WAF rule that was blocked.

attack_passed_req_body_bytes integer

Total body bytes received from requests that triggered a WAF rule that was passed.

attack_passed_req_header_bytes integer

Total header bytes received from requests that triggered a WAF rule that was passed.

attack_resp_synth_bytes integer

Total bytes delivered for requests that triggered a WAF rule and returned a synthetic response.

imgopto integer

Number of responses that came from the Fastly Image Optimizer service.

imgopto_resp_body_bytes integer

Total body bytes delivered from the Fastly Image Optimizer service.

imgopto_resp_header_bytes integer

Total header bytes delivered from the Fastly Image Optimizer service.

imgopto_shield_resp_body_bytes integer

Total body bytes delivered via a shield from the Fastly Image Optimizer service.

imgopto_shield_resp_header_bytes integer

Total header bytes delivered via a shield from the Fastly Image Optimizer service.

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_400 integer

Number of responses sent with status code 400 (Bad Request).

status_401 integer

Number of responses sent with status code 401 (Unauthorized).

status_403 integer

Number of responses sent with status code 403 (Forbidden).

status_404 integer

Number of responses sent with status code 404 (Not Found).

status_416 integer

Number of responses sent with status code 416 (Range Not Satisfiable).

status_500 integer

Number of responses sent with status code 500 (Internal Server Error).

status_501 integer

Number of responses sent with status code 501 (Not Implemented).

status_502 integer

Number of responses sent with status code 502 (Bad Gateway).

status_503 integer

Number of responses sent with status code 503 (Service Unavailable).

status_504 integer

Number of responses sent with status code 504 (Gateway Timeout).

status_505 integer

Number of responses sent with status code 505 (HTTP Version Not Supported).

status_1xx integer

Number of "Informational" category status codes delivered.

status_2xx integer

Number of "Success" status codes delivered.

status_3xx integer

Number of "Redirection" codes delivered.

status_4xx integer

Number of "Client Error" codes delivered.

status_5xx integer

Number of "Server Error" codes delivered.

object_size_1k integer

Number of objects served that were under 1KB in size.

object_size_10k integer

Number of objects served that were between 1KB and 10KB in size.

object_size_100k integer

Number of objects served that were between 10KB and 100KB in size.

object_size_1m integer

Number of objects served that were between 100KB and 1MB in size.

object_size_10m integer

Number of objects served that were between 1MB and 10MB in size.

object_size_100m integer

Number of objects served that were between 10MB and 100MB in size.

object_size_1g integer

Number of objects served that were between 100MB and 1GB in size.

Actions

GET /stats

Fetches historical stats for each of your Fastly services and groups the results by service ID.

Authentication

API token.

Request Example
GET /stats?from=1+day+ago HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "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": {
    "6ElZZvtumbwtLBDJvFwepx": [
      {
        "requests": "1925645",
        "miss_time": "55.153864891000005",
        "start_time": "1368662400",
        "service_id": "6ElZZvtumbwtLBDJvFwepx",
        "bandwidth": "176544526854",
        "hits": "1902348",
        "hits_time": "520.0779119150006",
        "miss": "8354",
        "body_size": "175900019026",
        "pass": "4212",
        "header_size": "644507828",
        "req_header_bytes": "2905859973",
        "req_body_bytes": "390017958",
        "resp_header_bytes": "644507828",
        "resp_body_bytes": "175900019026",
        "bereq_header_bytes": "1870557109",
        "bereq_body_bytes": "389234083",
        "status_200": "1208426",
        "status_204": "0",
        "status_301": "0",
        "status_302": "0",
        "status_304": "0",
        "errors": "8418",
        "hit_ratio": "0.9956",
        "status_1xx": "0",
        "status_2xx": "1208426",
        "status_3xx": "0",
        "status_4xx": "708801",
        "status_503": "8418",
        "pipe": "0",
        "status_5xx": "8418",
        "uncacheable": "0",
        "tls": "2804069",
        "shield": "208055",
        "ipv6": "14156",
        "otfp": "12006",
        "video": "306053",
        "pci": "3041",
        "logging": "2088120",
        "http2": "251589",
        "waf_logged": "508",
        "waf_blocked": "360",
        "waf_passed": "0",
        "attack_req_body_bytes": "1274842",
        "attack_req_header_bytes": "892196",
        "attack_resp_synth_bytes": "0",
        "img_opto": "1404"
      }
    ],
    "5oYej0l0heMydtjaVPOq4z": [
      {
        "requests": "751",
        "miss_time": "1.198163271",
        "start_time": "1368662400",
        "service_id": "5oYej0l0heMydtjaVPOq4z",
        "bandwidth": "1159652",
        "hits": "743",
        "hits_time": "0.07059622299999999",
        "miss": "8",
        "body_size": "721082",
        "pass": "0",
        "header_size": "438570",
        "req_header_bytes": "2905859973",
        "req_body_bytes": "390017958",
        "resp_header_bytes": "438570",
        "resp_body_bytes": "721082",
        "bereq_header_bytes": "1870557109",
        "bereq_body_bytes": "389234083",
        "status_200": "580",
        "status_204": "0",
        "status_301": "2",
        "status_302": "0",
        "status_304": "169",
        "errors": "0",
        "hit_ratio": "0.9893",
        "status_1xx": "0",
        "status_2xx": "580",
        "status_3xx": "171",
        "status_4xx": "0",
        "status_503": "0",
        "pipe": "0",
        "status_5xx": "0",
        "uncacheable": "0",
        "tls": "2804069",
        "shield": "208055",
        "ipv6": "14156",
        "otfp": "12006",
        "video": "306053",
        "pci": "3041",
        "logging": "2088120",
        "http2": "251589",
        "waf_logged": "508",
        "waf_blocked": "360",
        "waf_passed": "0",
        "attack_req_body_bytes": "1274842",
        "attack_req_header_bytes": "892196",
        "attack_resp_synth_bytes": "0",
        "img_opto": "1404"
      }
    ]
  }
}
GET /stats/field/field

Fetches the specified field from the historical stats for each of your services and groups the results by service ID.

Authentication

API token.

Request Example
GET /stats/field/hit_ratio?from=6+hours+ago&to=3+hours+ago&by=hour HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "meta": {
    "to": "Thu May 16 17:13:03 UTC 2013",
    "from": "Thu May 16 14:13:03 UTC 2013",
    "by": "hour",
    "region": "all"
  },
  "msg": null,
  "data": {
    "6ElZZvtumbwtLBDJvFwepx": [
      {
        "service_id": "6ElZZvtumbwtLBDJvFwepx",
        "start_time": "1368716400",
        "hit_ratio": "0.0000"
      },
      {
        "service_id": "6ElZZvtumbwtLBDJvFwepx",
        "start_time": "1368720000",
        "hit_ratio": "0.9769"
      },
      {
        "service_id": "6ElZZvtumbwtLBDJvFwepx",
        "start_time": "1368723600",
        "hit_ratio": "0.9944"
      }
    ],
    "5oYej0l0heMydtjaVPOq4z": [
      {
        "service_id": "5oYej0l0heMydtjaVPOq4z",
        "start_time": "1368716400",
        "hit_ratio": "0.9857"
      },
      {
        "service_id": "5oYej0l0heMydtjaVPOq4z",
        "start_time": "1368720000",
        "hit_ratio": "1.0000"
      },
      {
        "service_id": "5oYej0l0heMydtjaVPOq4z",
        "start_time": "1368723600",
        "hit_ratio": "1.0000"
      }
    ]
  }
}
GET /stats/aggregate

Fetches historical stats information aggregated across all of your Fastly services.

Authentication

API token.

Request Example
GET /stats/aggregate?from=1368563377&to=1368736177 HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "meta": {
    "to": "Thu May 16 20:29:37 UTC 2013",
    "from": "Tue May 14 20:29:37 UTC 2013",
    "by": "day",
    "region": "all"
  },
  "msg": null,
  "data": [
    {
      "requests": "7022557",
      "miss_time": "43342.54711368301",
      "start_time": "1368576000",
      "bandwidth": "33656143431",
      "hits": "1851903",
      "hits_time": "284.90881923000006",
      "miss": "74773",
      "body_size": "31118762171",
      "pass": "5076669",
      "header_size": "2537381260",
      "req_header_bytes": "2905859973",
      "req_body_bytes": "390017958",
      "resp_header_bytes": "2537381260",
      "resp_body_bytes": "31118762171",
      "bereq_header_bytes": "1870557109",
      "bereq_body_bytes": "389234083",
      "status_200": "6959769",
      "status_204": "0",
      "status_301": "3093",
      "status_302": "60",
      "status_304": "14135",
      "errors": "21642",
      "hit_ratio": "0.9612",
      "status_1xx": "0",
      "status_2xx": "6959769",
      "status_3xx": "17288",
      "status_4xx": "23855",
      "status_503": "21631",
      "pipe": "0",
      "status_5xx": "21642",
      "uncacheable": "0",
      "tls": "2804069",
      "shield": "208055",
      "ipv6": "14156",
      "otfp": "12006",
      "video": "306053",
      "pci": "3041",
      "logging": "2088120",
      "http2": "251589",
      "waf_logged": "508",
      "waf_blocked": "360",
      "waf_passed": "0",
      "attack_req_body_bytes": "1274842",
      "attack_req_header_bytes": "892196",
      "attack_resp_synth_bytes": "0",
      "img_opto": "1404"
    },
    {
      "requests": "7908607",
      "miss_time": "31645.078110511986",
      "start_time": "1368662400",
      "bandwidth": "201478840738",
      "hits": "3455867",
      "hits_time": "751.2703607920007",
      "miss": "114580",
      "body_size": "198672905955",
      "pass": "4310192",
      "header_size": "2805934783",
      "req_header_bytes": "2905859973",
      "req_body_bytes": "390017958",
      "resp_header_bytes": "2805934783",
      "resp_body_bytes": "198672905955",
      "bereq_header_bytes": "1870557109",
      "bereq_body_bytes": "389234083",
      "status_200": "7128395",
      "status_204": "0",
      "status_301": "2649",
      "status_302": "30",
      "status_304": "9920",
      "errors": "41389",
      "hit_ratio": "0.9679",
      "status_1xx": "0",
      "status_2xx": "7128395",
      "status_3xx": "12599",
      "status_4xx": "726224",
      "status_503": "41246",
      "pipe": "0",
      "status_5xx": "41389",
      "uncacheable": "0",
      "tls": "2804069",
      "shield": "208055",
      "ipv6": "14156",
      "otfp": "12006",
      "video": "306053",
      "pci": "3041",
      "logging": "2088120",
      "http2": "251589",
      "waf_logged": "508",
      "waf_blocked": "360",
      "waf_passed": "0",
      "attack_req_body_bytes": "1274842",
      "attack_req_header_bytes": "892196",
      "attack_resp_synth_bytes": "0",
      "img_opto": "1404"
    }
  ]
}
GET /stats/service/service_id

Fetches historical stats for a given service.

Authentication

API token.

Request Example
GET /stats/service/1jlmtMz1ncwA0KC3TBGD0X?from=40+minutes+ago&to=38+minutes+ago&by=minute HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "meta": {
    "to": "Thu May 16 19:57:24 UTC 2013",
    "from": "Thu May 16 19:55:24 UTC 2013",
    "by": "minute",
    "region": "all"
  },
  "msg": null,
  "data": [
    {
      "requests": "21",
      "miss_time": "0",
      "start_time": "1368734160",
      "service_id": "1jlmtMz1ncwA0KC3TBGD0X",
      "bandwidth": "160238",
      "hits": "0",
      "hits_time": "0",
      "miss": "0",
      "body_size": "150948",
      "pass": "19",
      "header_size": "9290",
      "req_header_bytes": "2905859973",
      "req_body_bytes": "390017958",
      "resp_header_bytes": "9290",
      "resp_body_bytes": "150948",
      "bereq_header_bytes": "1870557109",
      "bereq_body_bytes": "389234083",
      "status_200": "14",
      "status_204": "0",
      "status_301": "2",
      "status_302": "0",
      "status_304": "0",
      "errors": "0",
      "hit_ratio": null,
      "status_1xx": "0",
      "status_2xx": "14",
      "status_3xx": "2",
      "status_4xx": "5",
      "status_503": "0",
      "pipe": "0",
      "status_5xx": "0",
      "uncacheable": "0",
      "tls": "2804069",
      "shield": "208055",
      "ipv6": "14156",
      "otfp": "12006",
      "video": "306053",
      "pci": "3041",
      "logging": "2088120",
      "http2": "251589",
      "waf_logged": "508",
      "waf_blocked": "360",
      "waf_passed": "0",
      "attack_req_body_bytes": "1274842",
      "attack_req_header_bytes": "892196",
      "attack_resp_synth_bytes": "0",
      "img_opto": "1404"
    },
    {
      "requests": "20",
      "miss_time": "0",
      "start_time": "1368734220",
      "service_id": "1jlmtMz1ncwA0KC3TBGD0X",
      "bandwidth": "156504",
      "hits": "0",
      "hits_time": "0",
      "miss": "0",
      "body_size": "147806",
      "pass": "17",
      "header_size": "8698",
      "req_header_bytes": "2905859973",
      "req_body_bytes": "390017958",
      "resp_header_bytes": "8698",
      "resp_body_bytes": "147806",
      "bereq_header_bytes": "1870557109",
      "bereq_body_bytes": "389234083",
      "status_200": "12",
      "status_204": "0",
      "status_301": "3",
      "status_302": "0",
      "status_304": "0",
      "errors": "0",
      "hit_ratio": null,
      "status_1xx": "0",
      "status_2xx": "12",
      "status_3xx": "3",
      "status_4xx": "5",
      "status_503": "0",
      "pipe": "0",
      "status_5xx": "0",
      "uncacheable": "0",
      "tls": "2804069",
      "shield": "208055",
      "ipv6": "14156",
      "otfp": "12006",
      "video": "306053",
      "pci": "3041",
      "logging": "2088120",
      "http2": "251589",
      "waf_logged": "508",
      "waf_blocked": "360",
      "waf_passed": "0",
      "attack_req_body_bytes": "1274842",
      "attack_req_header_bytes": "892196",
      "attack_resp_synth_bytes": "0",
      "img_opto": "1404"
    }
  ]
}
GET /stats/service/service_id/field/field

Fetches the specified field from the historical stats for a given service.

Authentication

API token.

Request Example
GET /stats/service/1jlmtMz1ncwA0KC3TBGD0X/field/bandwidth?from=2+days+ago HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "meta": {
    "to": "Thu May 16 20:39:09 UTC 2013",
    "from": "Tue May 14 20:39:09 UTC 2013",
    "by": "day",
    "region": "all"
  },
  "msg": null,
  "data": [
    {
      "service_id": "1jlmtMz1ncwA0KC3TBGD0X",
      "start_time": "1368576000",
      "bandwidth": "376983356"
    },
    {
      "service_id": "1jlmtMz1ncwA0KC3TBGD0X",
      "start_time": "1368662400",
      "bandwidth": "322029360"
    }
  ]
}
GET /stats/usage

Returns usage information aggregated across all Fastly services and grouped by region.

Authentication

API token.

Request Example
GET /stats/usage?from=1%2F1%2F2013&to=2%2F1%2F2013 HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "meta": {
    "to": "Fri Feb 01 12:00:00 UTC 2013",
    "from": "Tue Jan 01 12:00:00 UTC 2013",
    "by": "day",
    "region": "all"
  },
  "msg": null,
  "data": {
    "apac": {
      "requests": "163546563",
      "bandwidth": "10735282284"
    },
    "ausnz": {
      "requests": "2888860",
      "bandwidth": "173220202333"
    },
    "usa": {
      "requests": "163546563",
      "bandwidth": "153220202333"
    },
    "europe": {
      "requests": "2888860",
      "bandwidth": "10735282284"
    }
  }
}
GET /stats/usage_by_service

Returns usage information aggregated by service and grouped by service and region.

Authentication

API token.

Request Example
GET /stats/usage_by_service?from=2%2F1%2F2013&to=3%2F1%2F2013 HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "meta": {
    "to": "Fri Mar 01 12:00:00 UTC 2013",
    "from": "Fri Feb 01 12:00:00 UTC 2013",
    "by": "day",
    "region": "all"
  },
  "msg": null,
  "data": {
    "apac": {
      "1iPMGAF44YgzB7sINv4KTF": {
        "requests": "60524",
        "bandwidth": "6004223792"
      },
      "7mai6mbwRz0JXxhAY8ZSN2": {
        "requests": "3",
        "bandwidth": "1305"
      }
    },
    "ausnz": {
      "1iPMGAF44YgzB7sINv4KTF": {
        "requests": "101120",
        "bandwidth": "1735577606"
      },
      "7mai6mbwRz0JXxhAY8ZSN2": {
        "requests": "93294",
        "bandwidth": "38109995"
      }
    },
    "usa": {
      "1iPMGAF44YgzB7sINv4KTF": {
        "requests": "1109033",
        "bandwidth": "21642401706"
      },
      "7mai6mbwRz0JXxhAY8ZSN2": {
        "requests": "348175",
        "bandwidth": "173135847"
      }
    },
    "europe": {
      "1iPMGAF44YgzB7sINv4KTF": {
        "requests": "567583",
        "bandwidth": "14813592344"
      },
      "7mai6mbwRz0JXxhAY8ZSN2": {
        "requests": "260025",
        "bandwidth": "110928988"
      }
    }
  }
}
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.

Authentication

API token.

Parameters
parameter type description
month integer

2-digit month.

year integer

4-digit year.

billable_units string

If 'true', return results as billable units.

Request Example
GET /stats/usage_by_month?month=7&year=2017&billable_units=true HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "msg": null,
  "meta": {
    "from": "2017-07-01 00:00:00 +0000",
    "to": "2017-07-31 23:59:59 +0000",
    "by": "day",
    "region": "all"
  },
  "data": {
    "customer_id": "YOUR_CUSTOMER_ID",
    "services": {
      "SERVICE_ID": {
        "name": "SERVICE_NAME",
        "anzac": {
          "bandwidth": 28.815130509,
          "requests": 131.7256
        },
        "asia": {
          "bandwidth": 180.182470562,
          "requests": 965.4324
        },
        "europe": {
          "bandwidth": 1230.23131801,
          "requests": 6082.2894
        },
        "latam": {
          "bandwidth": 18.070301895,
          "requests": 93.7146
        },
        "south_africa": {
          "bandwidth": 8.77620445,
          "requests": 37.9704
        },
        "usa": {
          "bandwidth": 2330.717545144,
          "requests": 5524.7604
        }
      }
    },
    "total": {
      "anzac": {
        "bandwidth": 28.815130509,
        "requests": 131.7256
      },
      "asia": {
        "bandwidth": 180.182470562,
        "requests": 965.4324
      },
      "europe": {
        "bandwidth": 1230.23131801,
        "requests": 6082.2894
      },
      "latam": {
        "bandwidth": 18.070301895,
        "requests": 93.7146
      },
      "south_africa": {
        "bandwidth": 8.77620445,
        "requests": 37.9704
      },
      "usa": {
        "bandwidth": 2330.717545144,
        "requests": 5524.7604
      }
    }
  }
}
GET /stats/regions

Fetches the list of codes for regions that are covered by the Fastly CDN service.

Authentication

API token.

Request Example
GET /stats/regions HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "success",
  "meta": {
    "to": "Thu May 16 19:52:15 UTC 2013",
    "from": "Tue Apr 16 19:52:15 UTC 2013",
    "by": "day",
    "region": "all"
  },
  "msg": null,
  "data": [
    "apac",
    "ausnz",
    "usa",
    "europe"
  ]
}