Historical stats

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

Data latency

As a general rule, data with minute, hour, and day resolution will each be delayed by approximately 10 to 15 minutes due to the time it takes to collect and process historical data. Therefore time periods that are yet to complete or which have only recently ended may return data which is yet to fully count all traffic for that period.

IMPORTANT: You cannot retrieve data at minute resolution that is older than 90 days. Contact support@fastly.com if you require higher resolution.

Query options (Time range, Sampling rate, and Regions)

The following query parameters control the information which is returned by the historical stats API.

fromnumberTimestamp that defines the start of the window for which to fetch statistics, including the timestamp itself. Accepts Unix timestamps, or any form of input parsable by the Chronic Ruby library, such as 'yesterday', or 'two weeks ago'. Default varies based on the value of by (see note below)
tonumberTimestamp that defines the end of the window for which to fetch statistics. Accepts the same formats as from. Defaults to 'now'.
bystringDuration of sample windows (defaults to 'day')
minuteGroup data by minute
hourGroup data by hour
dayGroup data by day
regionstringLimit query to a specific geographic region
usaContinental United States
europeEurope
anzacAustralia and New Zealand
asiaAsia
asia_indiaIndia
latamBrazil
south_africaSouthern Africa
southamerica_stdSouth America

When the from or to parameters specify a date without a time, the time component will be set to 00:00. To specify a different time, use a Unix timestamp or an expression such as from=2013-01-01%2008:00&to=2013-01-02%2008:00

If from is omitted, the time range will start at a point determined by the value of by:

  • /stats or /stats?by=day: one month ago
  • /stats?by=hour: one day ago
  • /stats?by=minute: 30 minutes ago

If you define values for all of the from, to, and by parameters you can accidentally ask for a very large data set. We will not process exceedingly large queries.

IMPORTANT: All absolute time references in the historical stats API are UTC.

Examples

Returns stats grouped by day, for the last ten days, across all regions:

/stats?from=10+days+ago

Stats from Tuesday 14th May 2017 @ 20:29:37 UTC to Thursday 16th May 2017 @ 20:29:37 UTC:

/stats?from=1494793777&to=1494966577

Daily stats from January 1st, 2017 (1/1/2017) to February 1st, 2017 (2/1/2017):

/stats?from=1%2F1%2F2017&to=2%2F1%2F2017

Returns stats for only US POPs

/stats?region=usa

Returns stats for European POPs only:

/stats?region=europe

Response envelope

The result for this API has a unique wrapper envelope which provides status information and echoes the parameters used for the query:

/stats?from=10+days+ago
{
"status": "success",
"meta": {
"to": "Thu May 16 20:08:35 UTC 2013",
"from": "Wed May 6 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. data is an object, dividing results by service ID, and each individual service ID is an array where each element is one time span. Each of these elements, which describes a single service over the appropriate time span, is an object with the shape described below.

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.

Data model

requestsIntegerNumber of requests processed.
hitsIntegerNumber of cache hits.
hits_timeFloatTotal amount of time spent processing cache hits (in seconds).
missIntegerNumber of cache misses.
miss_timeFloatTotal amount of time spent processing cache misses (in seconds).
passIntegerNumber of requests that passed through the CDN without being cached.
pass_timeFloatTotal amount of time spent processing cache passes (in seconds).
errorsIntegerNumber of cache errors.
restartsIntegerNumber of restarts performed.
hit_ratioFloatRatio of cache hits to cache misses (between 0 and 1).
bandwidthIntegerTotal bytes delivered (resp_header_bytes + resp_body_bytes + bereq_header_bytes + bereq_body_bytes).
body_sizeIntegerTotal body bytes delivered (alias for resp_body_bytes).
header_sizeIntegerTotal header bytes delivered (alias for resp_header_bytes).
req_body_bytesIntegerTotal body bytes received.
req_header_bytesIntegerTotal header bytes received.
resp_body_bytesIntegerTotal body bytes delivered (edge_resp_body_bytes + shield_resp_body_bytes).
resp_header_bytesIntegerTotal header bytes delivered (edge_resp_header_bytes + shield_resp_header_bytes).
bereq_body_bytesIntegerTotal body bytes sent to origin.
bereq_header_bytesIntegerTotal header bytes sent to origin.
uncacheableIntegerNumber of requests that were designated uncachable.
pipeIntegerOptional. Pipe operations performed (legacy feature).
tlsIntegerNumber of requests that were received over TLS.
tls_v10IntegerNumber of requests received over TLS 1.0.
tls_v11IntegerNumber of requests received over TLS 1.1.
tls_v12IntegerNumber of requests received over TLS 1.2.
tls_v13IntegerNumber of requests received over TLS 1.3.
edge_requestsIntegerNumber of requests sent by end users to Fastly.
edge_resp_header_bytesIntegerTotal header bytes delivered from Fastly to the end user.
edge_resp_body_bytesIntegerTotal body bytes delivered from Fastly to the end user.
origin_fetchesIntegerNumber of requests sent to origin.
origin_fetch_header_bytesIntegerTotal request header bytes sent to origin.
origin_fetch_body_bytesIntegerTotal request body bytes sent to origin.
origin_fetch_resp_header_bytesIntegerTotal header bytes received from origin.
origin_fetch_resp_body_bytesIntegerTotal body bytes received from origin.
origin_revalidationsIntegerNumber of responses received from origin with a 304 status code in response to an If-Modified-Since or If-None-Match request. Under regular scenarios, a revalidation will imply a cache hit. However, if using Fastly Image Optimizer or segmented caching this may result in a cache miss.
shieldIntegerNumber of requests from edge to the shield POP.
shield_resp_body_bytesIntegerTotal body bytes delivered via a shield.
shield_resp_header_bytesIntegerTotal header bytes delivered via a shield.
shield_fetchesIntegerNumber of requests made from one Fastly data center to another, as part of shielding.
shield_fetch_header_bytesIntegerTotal request header bytes sent to a shield.
shield_fetch_body_bytesIntegerTotal request body bytes sent to a shield.
shield_fetch_resp_header_bytesIntegerTotal response header bytes sent from a shield to the edge.
shield_fetch_resp_body_bytesIntegerTotal response body bytes sent from a shield to the edge.
shield_revalidationsIntegerNumber of responses received from origin with a 304 status code, in response to an If-Modified-Since or If-None-Match request to a shield. Under regular scenarios, a revalidation will imply a cache hit. However, if using segmented caching this may result in a cache miss.
ipv6IntegerNumber of requests that were received over IPv6.
otfpIntegerNumber of responses that came from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.
otfp_resp_body_bytesIntegerTotal body bytes delivered from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.
otfp_resp_header_bytesIntegerTotal header bytes delivered from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.
otfp_shield_resp_body_bytesIntegerTotal 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_bytesIntegerTotal header bytes delivered via a shield for the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.
otfp_manifestsIntegerNumber of responses that were manifest files from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand.
otfp_deliver_timeFloatTotal 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_timeFloatTotal amount of time spent delivering a response via a shield from the Fastly On-the-Fly Packager for On Demand Streaming service for video-on-demand (in seconds).
videoIntegerNumber 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).
pciIntegerNumber of responses with the PCI flag turned on.
logIntegerNumber of log lines sent.
log_bytesIntegerTotal log bytes sent.
http2IntegerNumber of requests received over HTTP2.
waf_loggedIntegerNumber of requests that triggered a WAF rule and were logged.
waf_blockedIntegerNumber of requests that triggered a WAF rule and were blocked.
waf_passedIntegerNumber of requests that triggered a WAF rule and were passed.
attack_req_body_bytesIntegerTotal body bytes received from requests that triggered a WAF rule.
attack_req_header_bytesIntegerTotal header bytes received from requests that triggered a WAF rule.
attack_logged_req_body_bytesIntegerTotal body bytes received from requests that triggered a WAF rule that was logged.
attack_logged_req_header_bytesIntegerTotal header bytes received from requests that triggered a WAF rule that was logged.
attack_blocked_req_body_bytesIntegerTotal body bytes received from requests that triggered a WAF rule that was blocked.
attack_blocked_req_header_bytesIntegerTotal header bytes received from requests that triggered a WAF rule that was blocked.
attack_passed_req_body_bytesIntegerTotal body bytes received from requests that triggered a WAF rule that was passed.
attack_passed_req_header_bytesIntegerTotal header bytes received from requests that triggered a WAF rule that was passed.
attack_resp_synth_bytesIntegerTotal bytes delivered for requests that triggered a WAF rule and returned a synthetic response.
imgoptoIntegerNumber of responses that came from the Fastly Image Optimizer service.
imgopto_resp_body_bytesIntegerTotal body bytes delivered from the Fastly Image Optimizer service.
imgopto_resp_header_bytesIntegerTotal header bytes delivered from the Fastly Image Optimizer service.
imgopto_shield_resp_body_bytesIntegerTotal body bytes delivered via a shield from the Fastly Image Optimizer service.
imgopto_shield_resp_header_bytesIntegerTotal header bytes delivered via a shield from the Fastly Image Optimizer service.
imgvideoIntegerNumber of video responses that came from the Fastly Image Optimizer service.
imgvideo_framesIntegerNumber of video frames that came from the Fastly Image Optimizer service. A video frame is an individual image within a sequence of video.
imgvideo_resp_header_bytesIntegerTotal header bytes of video delivered from the Fastly Image Optimizer service.
imgvideo_resp_body_bytesIntegerTotal body bytes of video delivered from the Fastly Image Optimizer service.
imgvideo_shield_resp_header_bytesIntegerTotal header bytes of video delivered via a shield from the Fastly Image Optimizer service.
imgvideo_shield_resp_body_bytesIntegerTotal body bytes of video delivered via a shield from the Fastly Image Optimizer service.
imgvideo_shieldIntegerNumber of video responses delivered via a shield that came from the Fastly Image Optimizer service.
imgvideo_shield_framesIntegerNumber of video frames delivered via a shield that came from the Fastly Image Optimizer service. A video frame is an individual image within a sequence of video.
status_200IntegerNumber of responses sent with status code 200 (Success).
status_204IntegerNumber of responses sent with status code 204 (No Content).
status_206IntegerNumber of responses sent with status code 206 (Partial Content).
status_301IntegerNumber of responses sent with status code 301 (Moved Permanently).
status_302IntegerNumber of responses sent with status code 302 (Found).
status_304IntegerNumber of responses sent with status code 304 (Not Modified).
status_400IntegerNumber of responses sent with status code 400 (Bad Request).
status_401IntegerNumber of responses sent with status code 401 (Unauthorized).
status_403IntegerNumber of responses sent with status code 403 (Forbidden).
status_404IntegerNumber of responses sent with status code 404 (Not Found).
status_416IntegerNumber of responses sent with status code 416 (Range Not Satisfiable).
status_429IntegerNumber of responses sent with status code 429 (Too Many Requests).
status_500IntegerNumber of responses sent with status code 500 (Internal Server Error).
status_501IntegerNumber of responses sent with status code 501 (Not Implemented).
status_502IntegerNumber of responses sent with status code 502 (Bad Gateway).
status_503IntegerNumber of responses sent with status code 503 (Service Unavailable).
status_504IntegerNumber of responses sent with status code 504 (Gateway Timeout).
status_505IntegerNumber of responses sent with status code 505 (HTTP Version Not Supported).
status_1xxIntegerNumber of "Informational" category status codes delivered.
status_2xxIntegerNumber of "Success" status codes delivered.
status_3xxIntegerNumber of "Redirection" codes delivered.
status_4xxIntegerNumber of "Client Error" codes delivered.
status_5xxIntegerNumber of "Server Error" codes delivered.
object_size_1kIntegerNumber of objects served that were under 1KB in size.
object_size_10kIntegerNumber of objects served that were between 1KB and 10KB in size.
object_size_100kIntegerNumber of objects served that were between 10KB and 100KB in size.
object_size_1mIntegerNumber of objects served that were between 100KB and 1MB in size.
object_size_10mIntegerNumber of objects served that were between 1MB and 10MB in size.
object_size_100mIntegerNumber of objects served that were between 10MB and 100MB in size.
object_size_1gIntegerNumber of objects served that were between 100MB and 1GB in size.
recv_sub_timeFloatTime spent inside the 'recv' Varnish subroutine (in seconds).
recv_sub_countIntegerNumber of executions of the 'recv' Varnish subroutine.
hash_sub_timeFloatTime spent inside the 'hash' Varnish subroutine (in seconds).
hash_sub_countIntegerNumber of executions of the 'hash' Varnish subroutine.
miss_sub_timeFloatTime spent inside the 'miss' Varnish subroutine (in seconds).
miss_sub_countIntegerNumber of executions of the 'miss' Varnish subroutine.
fetch_sub_timeFloatTime spent inside the 'fetch' Varnish subroutine (in seconds).
fetch_sub_countIntegerNumber of executions of the 'fetch' Varnish subroutine.
pass_sub_timeFloatTime spent inside the 'pass' Varnish subroutine (in seconds).
pass_sub_countIntegerNumber of executions of the 'pass' Varnish subroutine.
pipe_sub_timeFloatTime spent inside the 'pipe' Varnish subroutine (in seconds).
pipe_sub_countIntegerNumber of executions of the 'pipe' Varnish subroutine.
deliver_sub_timeFloatTime spent inside the 'deliver' Varnish subroutine (in seconds).
deliver_sub_countIntegerNumber of executions of the 'deliver' Varnish subroutine.
error_sub_timeFloatTime spent inside the 'error' Varnish subroutine (in seconds).
error_sub_countIntegerNumber of executions of the 'error' Varnish subroutine.
hit_sub_timeFloatTime spent inside the 'hit' Varnish subroutine (in seconds).
hit_sub_countIntegerNumber of executions of the 'hit' Varnish subroutine.
prehash_sub_timeFloatTime spent inside the 'prehash' Varnish subroutine (in seconds).
prehash_sub_countIntegerNumber of executions of the 'prehash' Varnish subroutine.
predeliver_sub_timeFloatTime spent inside the 'predeliver' Varnish subroutine (in seconds).
predeliver_sub_countIntegerNumber of executions of the 'predeliver' Varnish subroutine.
tls_handshake_bytesIntegerNumber of bytes transferred during TLS handshake.
hit_resp_body_bytesIntegerTotal body bytes delivered for cache hits.
miss_resp_body_bytesIntegerTotal body bytes delivered for cache misses.
pass_resp_body_bytesIntegerTotal body bytes delivered for cache passes.
segblock_origin_fetchesIntegerNumber of Range requests to origin for segments of resources when using segmented caching.
segblock_shield_fetchesIntegerNumber of Range requests to a shield for segments of resources when using segmented caching.
compute_requestsIntegerThe total number of requests that were received for your site by Fastly.
compute_request_time_msFloatThe amount of active CPU time used to process your requests (in milliseconds).
compute_ram_usedIntegerThe amount of RAM used for your site by Fastly, including a maximum indicating the highest usage within this timeframe and a static cap for usage.
compute_execution_time_msFloatThe total, actual amount of time used to process your requests, including active CPU time (in milliseconds).

Endpoints

Get historical stats

GET/stats

Get historical stats for a single field

GET/stats/field/field

Get aggregated historical stats

GET/stats/aggregate

Get historical stats for a single service

GET/stats/service/service_id

Get historical stats for a single service/field combination

GET/stats/service/service_id/field/field

Get usage statistics

GET/stats/usage

Get usage statistics per service

GET/stats/usage_by_service

Get month-to-date usage statistics

GET/stats/usage_by_month

Get region codes

GET/stats/regions