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": ""
}

Reference - Previous

Client

Last updated 9 months ago

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

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.

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.

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

Metric	Description
total	Aggregated across all data points.
assetType	Aggregated across the given asset type (by extension).
originId	Aggregated across the given originId.

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

API

Authentication

Queries

Namespaces

Functions

Metrics

Ranges

Topic

Reference Table

Routes

getSpeed Metrics

getHistogram Metrics

getCache Metrics

getRank Metrics

get
Speed Metrics

get
Histogram Metrics

get
Cache Metrics

get
Rank Metrics