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 35 days. Contact support@fastly.com if you require data at minute resolution older than this.

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')
`region`	string	Limit query to a specific geographic region

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

`meta`	object	Meta information about the scope of the query in a human readable format.
`msg`	string	If the query was not successful, this will provide a string that explains why.
`status`	string	Whether or not we were able to successfully execute the query.
`data`	array

Results data model

The results of the query, grouped by service (and optionally, region), and aggregated over the appropriate time span.

`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_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_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_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_resp_synth_bytes`	integer	Total bytes delivered for requests that triggered a WAF rule and returned a synthetic response.
`bandwidth`	integer	Total bytes delivered (`resp_header_bytes` + `resp_body_bytes` + `bereq_header_bytes` + `bereq_body_bytes` + `compute_resp_header_bytes` + `compute_resp_body_bytes` + `compute_bereq_header_bytes` + `compute_bereq_body_bytes`).
`bereq_body_bytes`	integer	Total body bytes sent to origin.
`bereq_header_bytes`	integer	Total header bytes sent to origin.
`body_size`	integer	Total body bytes delivered (alias for resp_body_bytes).
`compute_bereq_body_bytes`	integer	Total body bytes sent to backends (origins) by Compute@Edge.
`compute_bereq_errors`	integer	Number of backend request errors, including timeouts.
`compute_bereq_header_bytes`	integer	Total header bytes sent to backends (origins) by Compute@Edge.
`compute_bereqs`	integer	Number of backend requests started.
`compute_beresp_body_bytes`	integer	Total body bytes received from backends (origins) by Compute@Edge.
`compute_beresp_header_bytes`	integer	Total header bytes received from backends (origins) by Compute@Edge.
`compute_execution_time_ms`	number	The amount of active CPU time used to process your requests (in milliseconds).
`compute_globals_limit_exceeded`	integer	Number of times a guest exceeded its globals limit.
`compute_guest_errors`	integer	Number of times a service experienced a guest code error.
`compute_heap_limit_exceeded`	integer	Number of times a guest exceeded its heap limit.
`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_req_body_bytes`	integer	Total body bytes received by Compute@Edge.
`compute_req_header_bytes`	integer	Total header bytes received by Compute@Edge.
`compute_request_time_ms`	number	The total, actual amount of time used to process your requests, including active CPU time (in milliseconds).
`compute_requests`	integer	The total number of requests that were received for your site by Fastly.
`compute_resource_limit_exceeded`	integer	Number of times a guest exceeded its resource limit, includes heap, stack, globals, and code execution timeout.
`compute_resp_body_bytes`	integer	Total body bytes sent from Compute@Edge to end user.
`compute_resp_header_bytes`	integer	Total header bytes sent from Compute@Edge to end user.
`compute_resp_status_1xx`	integer	Number of "Informational" category status codes delivered by Compute@Edge.
`compute_resp_status_2xx`	integer	Number of "Success" category status codes delivered by Compute@Edge.
`compute_resp_status_3xx`	integer	Number of "Redirection" category status codes delivered by Compute@Edge.
`compute_resp_status_4xx`	integer	Number of "Client Error" category status codes delivered by Compute@Edge.
`compute_resp_status_5xx`	integer	Number of "Server Error" category status codes delivered by Compute@Edge.
`compute_runtime_errors`	integer	Number of times a service experienced a guest runtime error.
`compute_stack_limit_exceeded`	integer	Number of times a guest exceeded its stack limit.
`deliver_sub_count`	integer	Number of executions of the `vcl_deliver` Varnish subroutine.
`deliver_sub_time`	number	Time spent inside the `vcl_deliver` Varnish subroutine (in seconds).
`edge_hit_requests`	integer	Number of requests sent by end users to Fastly that resulted in a hit at the edge.
`edge_miss_requests`	integer	Number of requests sent by end users to Fastly that resulted in a miss at the edge.
`edge_requests`	integer	Number of requests sent by end users to Fastly.
`edge_resp_body_bytes`	integer	Total body bytes delivered from Fastly to the end user.
`edge_resp_header_bytes`	integer	Total header bytes delivered from Fastly to the end user.
`error_sub_count`	integer	Number of executions of the `vcl_error` Varnish subroutine.
`error_sub_time`	number	Time spent inside the `vcl_error` Varnish subroutine (in seconds).
`errors`	integer	Number of cache errors.
`fetch_sub_count`	integer	Number of executions of the `vcl_fetch` Varnish subroutine.
`fetch_sub_time`	number	Time spent inside the `vcl_fetch` Varnish subroutine (in seconds).
`hash_sub_count`	integer	Number of executions of the `vcl_hash` Varnish subroutine.
`hash_sub_time`	number	Time spent inside the `vcl_hash` Varnish subroutine (in seconds).
`header_size`	integer	Total header bytes delivered (alias for resp_header_bytes).
`hit_ratio`	number	Ratio of cache hits to cache misses (between 0 and 1).
`hit_resp_body_bytes`	integer	Total body bytes delivered for cache hits.
`hit_sub_count`	integer	Number of executions of the `vcl_hit` Varnish subroutine.
`hit_sub_time`	number	Time spent inside the `vcl_hit` Varnish subroutine (in seconds).
`hits`	integer	Number of cache hits.
`hits_time`	number	Total amount of time spent processing cache hits (in seconds).
`http2`	integer	Number of requests received over HTTP/2.
`http3`	integer	Number of requests received over HTTP/3.
`imgopto`	integer	Number of responses that came from the Fastly Image Optimizer service. If the service receives 10 requests for an image, this stat will be 10 regardless of how many times the image was transformed.
`imgopto_resp_body_bytes`	integer	Total body bytes delivered from the Fastly Image Optimizer service, including shield traffic.
`imgopto_resp_header_bytes`	integer	Total header bytes delivered from the Fastly Image Optimizer service, including shield traffic.
`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.
`imgvideo`	number	Number of video responses that came from the Fastly Image Optimizer service.
`imgvideo_frames`	number	Number 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_body_bytes`	number	Total body bytes of video delivered from the Fastly Image Optimizer service.
`imgvideo_resp_header_bytes`	number	Total header bytes of video delivered from the Fastly Image Optimizer service.
`imgvideo_shield`	number	Number of video responses delivered via a shield that came from the Fastly Image Optimizer service.
`imgvideo_shield_frames`	number	Number 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.
`imgvideo_shield_resp_body_bytes`	number	Total body bytes of video delivered via a shield from the Fastly Image Optimizer service.
`imgvideo_shield_resp_header_bytes`	number	Total header bytes of video delivered via a shield from the Fastly Image Optimizer service.
`ipv6`	integer	Number of requests that were received over IPv6.
`log`	integer	Number of log lines sent.
`log_bytes`	integer	Total log bytes sent.
`miss`	integer	Number of cache misses.
`miss_resp_body_bytes`	integer	Total body bytes delivered for cache misses.
`miss_sub_count`	integer	Number of executions of the `vcl_miss` Varnish subroutine.
`miss_sub_time`	number	Time spent inside the `vcl_miss` Varnish subroutine (in seconds).
`miss_time`	number	Total amount of time spent processing cache misses (in seconds).
`object_size_100k`	integer	Number of objects served that were between 10KB and 100KB in size.
`object_size_100m`	integer	Number of objects served that were between 10MB and 100MB in size.
`object_size_10k`	integer	Number of objects served that were between 1KB and 10KB in size.
`object_size_10m`	integer	Number of objects served that were between 1MB and 10MB in size.
`object_size_1g`	integer	Number of objects served that were between 100MB and 1GB in size.
`object_size_1k`	integer	Number of objects served that were under 1KB in size.
`object_size_1m`	integer	Number of objects served that were between 100KB and 1MB in size.
`origin_cache_fetches`	integer	The total number of completed requests made to backends (origins) that returned cacheable content.
`origin_fetch_body_bytes`	integer	Total request body bytes sent to origin.
`origin_fetch_header_bytes`	integer	Total request header bytes sent to origin.
`origin_fetch_resp_body_bytes`	integer	Total body bytes received from origin.
`origin_fetch_resp_header_bytes`	integer	Total header bytes received from origin.
`origin_fetches`	integer	Number of requests sent to 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.
`otfp`	integer	Number of responses that came from the Fastly On-the-Fly Packaging service for video-on-demand.
`otfp_deliver_time`	number	Total amount of time spent delivering a response from the Fastly On-the-Fly Packaging service for video-on-demand (in seconds).
`otfp_manifests`	integer	Number of responses that were manifest files from the Fastly On-the-Fly Packaging service for video-on-demand.
`otfp_resp_body_bytes`	integer	Total body bytes delivered from the Fastly On-the-Fly Packaging service for video-on-demand.
`otfp_resp_header_bytes`	integer	Total header bytes delivered from the Fastly On-the-Fly Packaging service for video-on-demand.
`otfp_shield_resp_body_bytes`	integer	Total body bytes delivered via a shield for the Fastly On-the-Fly Packaging service for video-on-demand.
`otfp_shield_resp_header_bytes`	integer	Total header bytes delivered via a shield for the Fastly On-the-Fly Packaging service for video-on-demand.
`otfp_shield_time`	number	Total amount of time spent delivering a response via a shield from the Fastly On-the-Fly Packaging service for video-on-demand (in seconds).
`pass`	integer	Number of requests that passed through the CDN without being cached.
`pass_resp_body_bytes`	integer	Total body bytes delivered for cache passes.
`pass_sub_count`	integer	Number of executions of the `vcl_pass` Varnish subroutine.
`pass_sub_time`	number	Time spent inside the `vcl_pass` Varnish subroutine (in seconds).
`pass_time`	number	Total amount of time spent processing cache passes (in seconds).
`pci`	integer	Number of responses with the PCI flag turned on.
`pipe`	integer	Optional. Pipe operations performed (legacy feature).
`pipe_sub_count`	integer	Number of executions of the `vcl_pipe` Varnish subroutine.
`pipe_sub_time`	number	Time spent inside the `vcl_pipe` Varnish subroutine (in seconds).
`predeliver_sub_count`	integer	Number of executions of the `vcl_predeliver` Varnish subroutine.
`predeliver_sub_time`	number	Time spent inside the `vcl_predeliver` Varnish subroutine (in seconds).
`prehash_sub_count`	integer	Number of executions of the `vcl_prehash` Varnish subroutine.
`prehash_sub_time`	number	Time spent inside the `vcl_prehash` Varnish subroutine (in seconds).
`recv_sub_count`	integer	Number of executions of the `vcl_recv` Varnish subroutine.
`recv_sub_time`	number	Time spent inside the `vcl_recv` Varnish subroutine (in seconds).
`req_body_bytes`	integer	Total body bytes received.
`req_header_bytes`	integer	Total header bytes received.
`requests`	integer	Number of requests processed.
`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).
`restarts`	integer	Number of restarts performed.
`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.
`shield`	integer	Number of requests from edge to the shield POP.
`shield_cache_fetches`	integer	The total number of completed requests made to shields that returned cacheable content.
`shield_fetch_body_bytes`	integer	Total request body bytes sent to a shield.
`shield_fetch_header_bytes`	integer	Total request header bytes sent to a shield.
`shield_fetch_resp_body_bytes`	integer	Total response body bytes sent from a shield to the edge.
`shield_fetch_resp_header_bytes`	integer	Total response header bytes sent from a shield to the edge.
`shield_fetches`	integer	Number of requests made from one Fastly data center to another, as part of shielding.
`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_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.
`status_1xx`	integer	Number of "Informational" category status codes delivered.
`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_2xx`	integer	Number of "Success" status codes delivered.
`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_3xx`	integer	Number of "Redirection" codes delivered.
`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_4xx`	integer	Number of "Client Error" codes delivered.
`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_5xx`	integer	Number of "Server Error" codes delivered.
`synth`	integer	Number of requests that returned a synthetic response (i.e., response objects created with the `synthetic` VCL statement).
`tls`	integer	Number of requests that were received over TLS.
`tls_handshake_sent_bytes`	integer	Number of bytes transferred during TLS handshake.
`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.
`uncacheable`	integer	Number of requests that were designated uncachable.
`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).
`waf_blocked`	integer	Number of requests that triggered a WAF rule and were blocked.
`waf_logged`	integer	Number of requests that triggered a WAF rule and were logged.
`waf_passed`	integer	Number of requests that triggered a WAF rule and were passed.

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