Domain Inspector Historical API

Domain Inspector provides a JSON-formatted historical API for visibility into responses delivered from your domains by Fastly. The API offers a standardized set of data to report in minutely, hourly, or daily granularity on every domain response, byte, and status code received by a specified service.

IMPORTANT: Domain inspector is an optional upgrade to Fastly service plans and must be enabled for each service using the enablement API.

Query options

When the start or and 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 start=2021-01-01%2008:00&end=2021-01-02%2008:00

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

  • ?downsample=day: one month ago
  • ?downsample=hour: one day ago
  • ?downsample=minute: 30 minutes ago

If you define values for all of the start, end, and downsamples parameters you can accidentally ask for a very large data set.

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

Examples

Returns domain response counts for service abc123, summed by day, for the first week of September 2021:

/metrics/domains/services/abc123?start=2021-09-01&end=2021-09-08&downsample=day&metric=requests

Returns the count of 200 and 204 status codes emitted by domains for service abc123, summed by minute, for the first 8 hours of September 2021:

/metrics/domains/services/abc123?start=2021-09-01T00:00:00&end=2021-09-02T08:00:00&downsample=minute&metric=status_200,status_201

Returns the count of 5xx status codes emitted by domains for service abc123 on the first day of September 2021, with one timeseries per unique domain:

/metrics/domains/services/abc123?start=2021-09-01&end=2021-09-02&metric=status_5xx&group_by=domain

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 that doesn't yet fully count all traffic for that period.

Error format

Error responses have the Content-Type header set to application/problem+json. The error response body will include:

  • type (string): A URL that includes additional, human-readable information about this error type.
  • title (string): A short name for the error type.
  • status (integer): The HTTP status code.
  • detail (string): A human-readable description of the specific error.
  • errors (array): A list of individual errors, where multiple errors have occurred.

An example error can be seen below:

{
"type": "https://fastly.help/metrics/validation-error",
"title": "Request parameters were invalid.",
"status": 400,
"errors": [
{
"property": "metric",
"reason": "Unrecognized metric names: 'my_metric', 'my_metric2'"
}
],
"detail": "Parameters with invalid values: 'metric'"
}

Domain Inspector provides a JSON-formatted historical API for visibility into responses delivered from your domains by Fastly. The API offers a standardized set of data to report in minutely, hourly, or daily granularity on every domain response, byte, and status code received by a specified service.

Data model

The unique combination of dimensions associated with this timeseries.

datacenterstringThe POP from which the edge responses in this data entry were delivered. If unspecified, results are aggregated across POPs.
domainstringThe domain from which the edge responses in this data entry were delivered. If unspecified, results are aggregated across domains.
regionstringThe geographic region from which the edge responses in this data entry were delivered. If unspecified, results are aggregated across regions.
dimensionsobjectThe unique combination of dimensions associated with this timeseries.
metaobjectMeta information about the scope of the query in a human readable format.
msgstringIf the query was not successful, this will provide a string that explains why.
statusstringWhether or not we were able to successfully execute the query.
valuesarrayAn array of values representing the metric values at each point in time. Note that this dataset is sparse: only the keys with non-zero values will be included in the record.

Entry data model

dimensionsobjectThe unique combination of dimensions associated with this timeseries.
valuesarrayAn array of values representing the metric values at each point in time. Note that this dataset is sparse: only the keys with non-zero values will be included in the record.

Values data model

The results of the query, optionally filtered and grouped over the requested timespan.

bandwidthintegerTotal bytes delivered (resp_header_bytes + resp_body_bytes + bereq_header_bytes + bereq_body_bytes).
bereq_body_bytesintegerTotal body bytes sent to origin.
bereq_header_bytesintegerTotal header bytes sent to origin.
edge_hit_rationumberRatio of cache hits to cache misses at the edge, between 0 and 1 (edge_hit_requests / (edge_hit_requests + edge_miss_requests)).
edge_hit_requestsintegerNumber of requests sent by end users to Fastly that resulted in a hit at the edge.
edge_miss_requestsintegerNumber of requests sent by end users to Fastly that resulted in a miss at the edge.
edge_requestsintegerNumber of requests sent by end users to Fastly.
edge_resp_body_bytesintegerTotal body bytes delivered from Fastly to the end user.
edge_resp_header_bytesintegerTotal header bytes delivered from Fastly to the end user.
origin_fetch_resp_body_bytesintegerTotal body bytes received from origin.
origin_fetch_resp_header_bytesintegerTotal header bytes received from origin.
origin_fetchesintegerNumber of requests sent to origin.
origin_offloadnumberOrigin Offload measures the ratio of bytes served to end users that were cached by Fastly, over the bytes served to end users, between 0 and 1. ((edge_resp_body_bytes + edge_resp_header_bytes) - (origin_fetch_resp_body_bytes + origin_fetch_resp_header_bytes)) / (edge_resp_body_bytes + edge_resp_header_bytes). Previously, Origin Offload used a different formula. Learn more.
origin_status_1xxintegerNumber of "Informational" category status codes received from origin.
origin_status_200integerNumber of responses received from origin with status code 200 (Success).
origin_status_204integerNumber of responses received from origin with status code 204 (No Content).
origin_status_206integerNumber of responses received from origin with status code 206 (Partial Content).
origin_status_2xxintegerNumber of "Success" status codes received from origin.
origin_status_301integerNumber of responses received from origin with status code 301 (Moved Permanently).
origin_status_302integerNumber of responses received from origin with status code 302 (Found).
origin_status_304integerNumber of responses received from origin with status code 304 (Not Modified).
origin_status_3xxintegerNumber of "Redirection" codes received from origin.
origin_status_400integerNumber of responses received from origin with status code 400 (Bad Request).
origin_status_401integerNumber of responses received from origin with status code 401 (Unauthorized).
origin_status_403integerNumber of responses received from origin with status code 403 (Forbidden).
origin_status_404integerNumber of responses received from origin with status code 404 (Not Found).
origin_status_416integerNumber of responses received from origin with status code 416 (Range Not Satisfiable).
origin_status_429integerNumber of responses received from origin with status code 429 (Too Many Requests).
origin_status_4xxintegerNumber of "Client Error" codes received from origin.
origin_status_500integerNumber of responses received from origin with status code 500 (Internal Server Error).
origin_status_501integerNumber of responses received from origin with status code 501 (Not Implemented).
origin_status_502integerNumber of responses received from origin with status code 502 (Bad Gateway).
origin_status_503integerNumber of responses received from origin with status code 503 (Service Unavailable).
origin_status_504integerNumber of responses received from origin with status code 504 (Gateway Timeout).
origin_status_505integerNumber of responses received from origin with status code 505 (HTTP Version Not Supported).
origin_status_5xxintegerNumber of "Server Error" codes received from origin.
requestsintegerNumber of requests processed.
resp_body_bytesintegerTotal body bytes delivered.
resp_header_bytesintegerTotal header bytes delivered.
status_1xxintegerNumber of 1xx "Informational" category status codes delivered.
status_200integerNumber of responses delivered with status code 200 (Success).
status_204integerNumber of responses delivered with status code 204 (No Content).
status_206integerNumber of responses delivered with status code 206 (Partial Content).
status_2xxintegerNumber of 2xx "Success" status codes delivered.
status_301integerNumber of responses delivered with status code 301 (Moved Permanently).
status_302integerNumber of responses delivered with status code 302 (Found).
status_304integerNumber of responses delivered with status code 304 (Not Modified).
status_3xxintegerNumber of 3xx "Redirection" codes delivered.
status_400integerNumber of responses delivered with status code 400 (Bad Request).
status_401integerNumber of responses delivered with status code 401 (Unauthorized).
status_403integerNumber of responses delivered with status code 403 (Forbidden).
status_404integerNumber of responses delivered with status code 404 (Not Found).
status_416integerNumber of responses delivered with status code 416 (Range Not Satisfiable).
status_429integerNumber of responses delivered with status code 429 (Too Many Requests).
status_4xxintegerNumber of 4xx "Client Error" codes delivered.
status_500integerNumber of responses delivered with status code 500 (Internal Server Error).
status_501integerNumber of responses delivered with status code 501 (Not Implemented).
status_502integerNumber of responses delivered with status code 502 (Bad Gateway).
status_503integerNumber of responses delivered with status code 503 (Service Unavailable).
status_504integerNumber of responses delivered with status code 504 (Gateway Timeout).
status_505integerNumber of responses delivered with status code 505 (HTTP Version Not Supported).
status_5xxintegerNumber of 5xx "Server Error" codes delivered.

Endpoints

Get historical domain data for a service

GET/metrics/domains/services/service_id