Real-time Analytics | Fastly API Documentation

Fastly provides an HTTPS endpoint to poll for real-time analytics.

Endpoint

The base endpoint for the real-time analytics system is https://rt.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.

Channels

A channel ID is equivalent to a service ID, so each channel will provide real-time analytics for one service. The provided service ID must be owned by the account specified by the API token used for authentication.

There is a special channel ID demo which is used for the analytics on the fastly.com homepage.

URL structure

For regular real-time analytics, this call allows you to get (and potentially wait for) any messages after a given timestamp. A message covers a one second interval:

<endpoint>/v1/channel/<service id>/ts/<timestamp in seconds>

For the first request, the timestamp can be 0. The response will then return a new timestamp field which should be used for the next request.

There is also "History" call for fetching data from the previous 120 seconds up to the latest timestamp for a channel:

<endpoint>/v1/channel/<service id>/ts/h

This can be modified by fetching the last N entries.

<endpoint>/v1/channel/<service id>/ts/h/limit/<N>

Response structure

The response is a JSON object. The top level object has two keys: Timestamp and Data. The Timestamp value should be extracted and used for the next API call, e.g.:

Set Timestamp to 0
Make API call
Set Timestamp to Timestamp value of returned JSON object
Do something with the rest of the data
Goto #2

The Data value is a JSON array. For regular real-time analytics calls, it will only have one or two items. For the history call, it will have as many items as were requested.

{
  "Timestamp" => 1467915558,
  "Data" => [ ... ]
}

Each item is a JSON object with two keys: recorded is a Unix time stamp (e.g., seconds since Jan 1st, 1970) of when this data was generated on our cache servers, and datacenter with another JSON object as a value.

"Data" => [
  {
    "recorded"   => 1467915558,
    "datacenter" => {...}
  },
  ...
]

The keys of the datacenter JSON object are the names of each of our POPs around the world plus a special key, called aggregated, which adds all the values from all the POPs together.

{
   "Data":[
      {
         "datacenter":{
             "AMS" => { ... },
             "SIN" => { ... },
             "SJC" => { ... },
             ...
         },
         "aggregated":{  },
         "recorded":1478140705
      }
   ],
   "Timestamp":1478140713
}

The value of each of the POP keys is another JSON object that has various statistics. For example, here are the statistics for our San Jose POP during that time:

"SJC" => {
  "requests"          => 45,
  "resp_header_bytes" => 22018,
  "resp_body_bytes"   => 134564,
  "hits"              => 200,
  "miss"              => 48,
  "synth"             => 4,
  "errors"            => 5,
  "hits_time"         => 200,
  "miss_time"         => 1800,
  "miss_histogram"  => {
    "80"   => 33,
    "90"   => 1,
    "110"  => 1,
    "170"  => 1,
    "250"  => 1,
    "300"  => 2,
    "400"  => 1,
    "650"  => 2,
    "750"  => 1,
    "1000" => 1,
    "1100" => 1
  }
}

The keys are the same as those mentioned on the Historical Stats page, but they show some statistics that have occurred since the last request, including the following:

Number of requests
Number of bytes transmitted in headers
Number of bytes transmitted in bodies
Number of hits
Number of misses
Number of synthetic responses
Number of errors
Amount of time spent delivering hits
Amount of time spent delivering misses

The miss_histogram object is a JSON object. The keys are time buckets in 10s of milliseconds, and the values are the number of requests to origin. In this example provided above, 33 requests went to origin that took between 80 and 89 milliseconds to fetch.

The miss_histogram tops out at 60s. Any origin request that takes more than 60 seconds to return will be in the 60000 bucket.

Rate limiting

The real-time analytics API is rate limited internally. However, it is also cached behind Fastly with an expiration time of 1s. Under normal use there should be no reason for customers to hit that rate limit.

API reference