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.
from | number | Timestamp 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) |
to | number | Timestamp that defines the end of the window for which to fetch statistics. Accepts the same formats as from. Defaults to 'now'. |
by | string | Duration of sample windows (defaults to 'day') |
minute | Group data by minute | |
hour | Group data by hour | |
day | Group data by day | |
region | string | Limit query to a specific geographic region |
usa | Continental United States | |
europe | Europe | |
anzac | Australia and New Zealand | |
asia | Asia | |
asia_india | India | |
latam | Brazil | |
south_africa | Southern Africa | |
southamerica_std | South 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:
/statsor/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+agoStats from Tuesday 14th May 2017 @ 20:29:37 UTC to Thursday 16th May 2017 @ 20:29:37 UTC:
/stats?from=1494793777&to=1494966577Daily stats from January 1st, 2017 (1/1/2017) to February 1st, 2017 (2/1/2017):
/stats?from=1%2F1%2F2017&to=2%2F1%2F2017Returns stats for only US POPs
/stats?region=usaReturns stats for European POPs only:
/stats?region=europeResponse 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 querymeta- Meta information about the scope of the query in a human readable formatmsg- If the query was not successful this will provide a string that explains whydata- This contains the actual results of the query that we processed.datais 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
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 | Total 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 | Total 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 (edge_resp_body_bytes + shield_resp_body_bytes). |
resp_header_bytes | Integer | Total header bytes delivered (edge_resp_header_bytes + shield_resp_header_bytes). |
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. |
edge_requests | Integer | Number of requests sent by end users to Fastly. |
edge_resp_header_bytes | Integer | Total header bytes delivered from Fastly to the end user. |
edge_resp_body_bytes | Integer | Total body bytes delivered from Fastly to the end user. |
origin_fetches | Integer | Number of requests sent to origin. |
origin_fetch_header_bytes | Integer | Total request header bytes sent to origin. |
origin_fetch_body_bytes | Integer | Total request body bytes sent to origin. |
origin_fetch_resp_header_bytes | Integer | Total header bytes received from origin. |
origin_fetch_resp_body_bytes | Integer | Total body bytes received from origin. |
origin_revalidations | Integer | Number 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. |
shield | Integer | Number of requests from edge to the shield POP. |
shield_resp_body_bytes | Integer | Total body bytes delivered via a shield. |
shield_resp_header_bytes | Integer | Total header bytes delivered via a shield. |
shield_fetches | Integer | Number of requests made from one Fastly data center to another, as part of shielding. |
shield_fetch_header_bytes | Integer | Total request header bytes sent to a shield. |
shield_fetch_body_bytes | Integer | Total request body bytes sent to a shield. |
shield_fetch_resp_header_bytes | Integer | Total response header bytes sent from a shield to the edge. |
shield_fetch_resp_body_bytes | Integer | Total response body bytes sent from a shield to the edge. |
shield_revalidations | Integer | Number 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. |
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 shield 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. |
log_bytes | Integer | Total log bytes 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_206 | Integer | Number of responses sent with status code 206 (Partial 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_429 | Integer | Number of responses sent with status code 429 (Too Many Requests). |
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. |
recv_sub_time | Float | Time spent inside the 'recv' Varnish subroutine (in seconds). |
recv_sub_count | Integer | Number of executions of the 'recv' Varnish subroutine. |
hash_sub_time | Float | Time spent inside the 'hash' Varnish subroutine (in seconds). |
hash_sub_count | Integer | Number of executions of the 'hash' Varnish subroutine. |
miss_sub_time | Float | Time spent inside the 'miss' Varnish subroutine (in seconds). |
miss_sub_count | Integer | Number of executions of the 'miss' Varnish subroutine. |
fetch_sub_time | Float | Time spent inside the 'fetch' Varnish subroutine (in seconds). |
fetch_sub_count | Integer | Number of executions of the 'fetch' Varnish subroutine. |
pass_sub_time | Float | Time spent inside the 'pass' Varnish subroutine (in seconds). |
pass_sub_count | Integer | Number of executions of the 'pass' Varnish subroutine. |
pipe_sub_time | Float | Time spent inside the 'pipe' Varnish subroutine (in seconds). |
pipe_sub_count | Integer | Number of executions of the 'pipe' Varnish subroutine. |
deliver_sub_time | Float | Time spent inside the 'deliver' Varnish subroutine (in seconds). |
deliver_sub_count | Integer | Number of executions of the 'deliver' Varnish subroutine. |
error_sub_time | Float | Time spent inside the 'error' Varnish subroutine (in seconds). |
error_sub_count | Integer | Number of executions of the 'error' Varnish subroutine. |
hit_sub_time | Float | Time spent inside the 'hit' Varnish subroutine (in seconds). |
hit_sub_count | Integer | Number of executions of the 'hit' Varnish subroutine. |
prehash_sub_time | Float | Time spent inside the 'prehash' Varnish subroutine (in seconds). |
prehash_sub_count | Integer | Number of executions of the 'prehash' Varnish subroutine. |
predeliver_sub_time | Float | Time spent inside the 'predeliver' Varnish subroutine (in seconds). |
predeliver_sub_count | Integer | Number of executions of the 'predeliver' Varnish subroutine. |
tls_handshake_bytes | Integer | Number of bytes transferred during TLS handshake. |
hit_resp_body_bytes | Integer | Total body bytes delivered for cache hits. |
miss_resp_body_bytes | Integer | Total body bytes delivered for cache misses. |
pass_resp_body_bytes | Integer | Total body bytes delivered for cache passes. |
segblock_origin_fetches | Integer | Number of Range requests to origin for segments of resources when using segmented caching. |
segblock_shield_fetches | Integer | Number of Range requests to a shield for segments of resources when using segmented caching. |
compute_requests | Integer | The total number of requests that were received for your site by Fastly. |
compute_request_time_ms | Float | The amount of active CPU time used to process your requests (in milliseconds). |
compute_ram_used | Integer | The 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_ms | Float | The total, actual amount of time used to process your requests, including active CPU time (in milliseconds). |
Endpoints
User contributed notes
We welcome comments that add use cases, ideas, tips, and caveats. All comments will be moderated before publication. To post support questions, visit our support center and we'll find you the help you need.