API

The Edgemesh Analytics API.

The Edgemesh Analytics API is currently in closed beta. Contact an Edgemesh support agent if you would like to gain access to the beta.

Authentication

This API requires a token be sent on every request. Currently, tokens are issued by Edgemesh to our beta users. Once you have received your token, you can authenticate your request by adding the token to the Authorization header, the token field in the request body or the token query parameter.

Queries

Namespaces

The Metrics API is organized by Namespace. Each Namespace corresponds to a specific area of study for your system. The following Namespaces are available:

Namespace

Description

speed

A breakdown of your sites performance over a given METRIC expressed as buckets of Fast, Slow or Average performance. This method is similar to the data aggregation used by Google for the Chrome Real User Experience rankings.

histogram

A breakdown of the individual performance counts for a given METRIC. The Histogram namespace allows you to extract distributions and values for multiple percentiles across your entire data set.

rank

A comparative breakdown of your sites performance vs. the universe of Edgemesh clients. This helps you analyze if your METRIC is inline with your peers, or falling behind.

cache

Detailed information on the performance of the Edgemesh client side cache. This includes information on your Cache Hit Rate (what % of data was serviced by the browser side Edgemesh cache), Pre-cache Hit Rate (how efficient was Edgemesh at correctly guessing and pre-caching content) and the overall asset count your visitor's experienced.

Functions

The following functions are available for all queries:

Function

Description

summary

Summary functions provide an aggregated view of the given metric for Total

timeseries

Timeseries functions return the histogram values as embedded (nested) vectors. Each value corresponds to the count of page views in that bucket (100ms buckets).

prange

The same as the summary functions except prange includes multiple data points bucketed by datetime.

Metrics

The metrics available to query are outlined below along with their fast and slow thresholds. These metrics are applicable to the speed and histogram namespaces.

Metric

Description

Fast Threshold

Slow Threshold

ttfb

Time to First Byte

100

500

fp

First Paint

500

2000

tti

Time to Interactive

1000

2500

cl

Content Loaded

1500

3000

These are the available metrics for the cache namespace.

Metric

Description

total

Aggregated across all data points.

assetType

Aggregated across the given asset type (by extension).

originId

Aggregated across the given originId.

Ranges

The following date ranges are accepted by all queries:

Range

Bucket Size

Data Points

day

1 Hour

24-25

week

8 Hours (1/3 Day)

21-22

month

24 Hours (1 Day)

30-31

quarter

96 Hours (4 Days)

30-31

year

336 Hours (14 Days)

26-27

Topic

A topic is a unique identifier for your domain. To get your topic, you can visit our Portal or you can go to your Edgemesh enabled site and enter copy(edgemesh._topic) in the javascript console and your Topic will be copied to your clipboard. A valid topic is a hex representation of a 64bit integer. It should begin with 0x and be a total if 18 characters long.

Reference Table

Namespaces

Functions | metrics

speed

histogram

rank

cache

summary

ttfb, fp, tti, cl

ttfb, fp, tti, cl

ttfb, fp, tti, cl

total, assetType, originId

timeseries

ttfb, fp, tti, cl

ttfb, fp, tti, cl

ttfb, fp, tti, cl

total, assetType, originId

prange

ttfb, fp, tti, cl

Routes

All of our routes follow the same signature:

<hostname>/:version/metrics/:namespace/:func/:metric/:range/:topic

Each namespace is outlined below including some example requests and responses. If you were to enter in a bad request, the resulting error will instruct you how to fix the issue.

get
Speed Metrics

https://api.edgemesh.com/v3/metrics/speed/:func/:metric/:range/:topic
The speed queries bucket page views into fast, average and slow for each of the supported metrics. Fast and slow are determined by the Metric Thresholds.
Request
Response
Request
Path Parameters
func
required
string
Function to call. One of summary or timeseries.
metric
required
string
Metric to query. One of ttfb, fp, tti or cl.
range
required
string
Time range to query. One of day, week, month, quarter, year.
topic
required
string
Topic to query.
Headers
Authentication
optional
string
Authentication token by request header.
Query Parameters
token
optional
string
Authentication token by query string parameter.
echo
optional
boolean
Echo back the original query in the response.
Response
200: OK
Speed metrics successfully received.
{
"startUTC": "2020-04-19T22:00:00.000Z",
"endUTC": "2020-04-20T22:00:00.000Z",
"cntFastA": 6,
"cntFastS": 0,
"cntSlowA": 6,
"cntSlowS": 2,
"cntAvgA": 9,
"cntAvgS": 0,
"cntAccel": 21,
"cntStand": 2,
"cntTotal": 23,
"pctFastA": 0.2857142857142857,
"pctSlowA": 0.2857142857142857,
"pctAvgA": 0.42857142857142855,
"pctFastS": 0,
"pctSlowS": 1,
"pctAvgS": 0
}
400: Bad Request
Bad requests will tell you where you went wrong.
{
"code": "BAD-REQ",
"statusCode": 400,
"message": "The parameter \"range\" requires type \"String[day | week | month | quarter | year]\" but received \"minute\".",
"details": ""
}
401: Unauthorized
Missing or invalid authentication.
{
"code": "FBDN-REQ",
"statusCode": 401,
"message": "\"Access denied. Your authentication is either missing, expired or invalid. Please refer to the documentation to learn how to set up authentication.",
"details": ""
}

get
Histogram Metrics

https://api.edgemesh.com/v3/metrics/histogram/:func/:metric/:range/:topic
Histogram functions provide an aggregated view of all page loads. The histogram query returns data in two dimensions, accelerated and standard page views.
Request
Response
Request
Path Parameters
func
required
string
Histogram function to query. One of summary, timeseries or prange.
metric
required
string
Metric to query. One of ttfb, fp, tti or cl.
range
required
string
Time range to query. One of day, week, month, quarter or year.
topic
required
string
Topic to query.
Headers
Authentication
optional
string
Authentication token by request header.
Query Parameters
token
optional
string
Authentication token by query string parameter.
echo
optional
boolean
Echo back the original query request.
Response
200: OK
{
"cntTotal": 24,
"p25Total": 100,
"p50Total": 300,
"p75Total": 900,
"p90Total": 1800,
"p95Total": 2300,
"p99Total": 2300,
"cntAccelerated": 22,
"p25Accelerated": 0,
"p50Accelerated": 200,
"p75Accelerated": 600,
"p90Accelerated": 1800,
"p95Accelerated": 2300,
"p99Accelerated": 2300,
"cntStandard": 2,
"p25Standard": 900,
"p50Standard": 1000,
"p75Standard": 1000,
"p90Standard": 1000,
"p95Standard": 1000,
"p99Standard": 1000
}
400: Bad Request
Bad requests will tell you where you went wrong.
{
"code": "BAD-REQ",
"statusCode": 400,
"message": "The parameter \"range\" requires type \"String[day | week | month | quarter | year]\" but received \"minute\".",
"details": ""
}
401: Unauthorized
Missing or invalid authentication.
{
"code": "FBDN-REQ",
"statusCode": 401,
"message": "\"Access denied. Your authentication is either missing, expired or invalid. Please refer to the documentation to learn how to set up authentication.",
"details": ""
}

get
Cache Metrics

https://api.edgemesh.com/v3/metrics/cache/:func/:metric/:range/:topic
The Cache Metrics API provides insights into the efficiency of the Edgemesh Client Cache. Edgemesh cache hits are when the browser is unable to serve and asset from either the in-memory cache or spillover disk cache. Edgemesh was the cache of last resort before going to the origin server (would have cache missed without Edgemesh). Cache Metrics have an additional metric that can be queried called originId. When querying for a specific originId, you will need to put the originId you want to query in the query string parameter.
Request
Response
Request
Path Parameters
func
required
string
Function to query. One of summary or timeseries.
metric
required
string
Metric to query. One of total, assetType or originId.
range
required
string
Time range to query. One of day, week, month, quarter or year.
topic
required
string
Topic to query.
Headers
Authentication
optional
string
Authentication token by request header.
Query Parameters
token
optional
string
Authentication token by query string parameter.
echo
optional
boolean
Echo back the original query request.
originId
optional
string
Used for the originId metric specific to cache queries.
Response
200: OK
Sample valid response from originId query.
{
"originId":[
"0x07ef265a7937d6ba",
"0xbf9d689b1be6c08d",
"0x1d8a70426f5daafa",
"0x804a57b1e41efb69",
"0x5001b8bd2284488d",
"0xdc03b22859fc75b4",
"0xf3a26610ff5c9621",
"0x538538d509f38c09",
"0xbff0f7bcc0b29fe1"
],
"total":[
478,
88,
32,
30,
28,
21,
18,
15,
1
],
"origin":[
432,
31,
10,
16,
18,
13,
12,
9,
0
],
"cached":[
43,
57,
22,
14,
10,
8,
6,
6,
1
],
"precached":[
3,
0,
0,
0,
0,
0,
0,
0,
0
],
"url":[
"https://edgemesh.com",
"https://www.google-analytics.com",
"https://www.facebook.com",
"https://js.driftt.com",
"https://connect.facebook.net",
"https://rte.edgeme.sh",
"https://static.edgeme.sh",
"https://www.googletagmanager.com",
"https://fonts.googleapis.com"
],
"resTimeMsP25":[
0,
1400,
0,
700,
0,
0,
2600,
1000,
0
],
"resTimeMsMedian":[
0,
2500,
0,
1000,
900,
0,
4400,
1800,
0
],
"resTimeMsP75":[
0,
4400,
0,
2100,
2600,
0,
7300,
3000,
0
],
"resTimeMsP90":[
0,
8200,
0,
3400,
4500,
0,
10000,
5000,
0
],
"cacheRate":[
0.09623430962343096,
0.6477272727272727,
0.6875,
0.4666666666666667,
0.35714285714285715,
0.38095238095238093,
0.3333333333333333,
0.4,
1
],
"preCacherate":[
0.006276150627615063,
0,
0,
0,
0,
0,
0,
0,
0
],
"preCacheEfficency":[
0.06976744186046512,
0,
0,
0,
0,
0,
0,
0,
0
]
}
400: Bad Request
Bad requests will tell you where you went wrong.
{
"code": "BAD-REQ",
"statusCode": 400,
"message": "The parameter \"range\" requires type \"String[day | week | month | quarter | year]\" but received \"minute\".",
"details": ""
}
401: Unauthorized
Missing or invalid authentication.
{
"code": "FBDN-REQ",
"statusCode": 401,
"message": "\"Access denied. Your authentication is either missing, expired or invalid. Please refer to the documentation to learn how to set up authentication.",
"details": ""
}

get
Rank Metrics

https://api.edgemesh.com/v3/metrics/rank/:func/:metric/:topic/:range
The rank query ranks your topic (domain) against all other Edgemesh enabled topics so you can see how your site stacks up in comparison.
Request
Response
Request
Path Parameters
func
required
string
Function to query. One of summary or timeseries.
metric
required
string
Metric to query. One of ttfb, fp, tti or cl.
range
required
string
Time range to query. One of day, week, month, quarter or year.
topic
required
string
Topic to query.
Headers
Authorization
optional
string
Authentication token by request header.
Query Parameters
token
optional
string
Authentication token by query string parameter.
echo
optional
boolean
Echo back the original query request.
Response
200: OK
Sample valid responses.
// Summary
{
"topicScore": 2500,
"topicStandingPct": 0.3251618,
"topicRank": "LOWER",
"rankBounds": {
"TOP_fastest": 0,
"TOP_slowest": 1300,
"MIDDLE_fastest": 1300,
"MIDDLE_slowest": 2500,
"LOWER_fastest": 2500,
"LOWER_slowest": 10100
}
}
// Timeseries
{
"datehh": [
"2020-04-15T22:00:00.000",
"2020-04-16T06:00:00.000"
],
"topicScore": [
2700,
2900
],
"topicStandingPct": [
0.2959622,
0.2903511
],
"rankBounds": [
{
"TOP_fastest": 0,
"TOP_slowest": 1400,
"MIDDLE_fastest": 1400,
"MIDDLE_slowest": 2600,
"LOWER_fastest": 2600,
"LOWER_slowest": 10000
},
{
"TOP_fastest": 0,
"TOP_slowest": 1500,
"MIDDLE_fastest": 1500,
"MIDDLE_slowest": 2700,
"LOWER_fastest": 2700,
"LOWER_slowest": 10100
}
],
"topicRank": [
"LOWER",
"LOWER"
]
}
400: Bad Request
Bad requests tell you where you went wrong.
{
"code": "BAD-REQ",
"statusCode": 400,
"message": "The parameter \"range\" requires type \"String[day | week | month | quarter | year]\" but received \"second\".",
"details": ""
}
401: Unauthorized
Missing or invalid authentication.
{
"code": "FBDN-REQ",
"statusCode": 401,
"message": "\"Access denied. Your authentication is either missing, expired or invalid. Please refer to the documentation to learn how to set up authentication.",
"details": ""
}