Description¶
This is how our Stats API works, which metrics are provided and how the aggregations are made. There are also some explanations of client errors.
Exposed Metrics¶
The following list describes the available metrics. All metrics refer to the latest time window:
| Name | Description |
|---|---|
| buffer health | The amount playback time (milliseconds) that remains on the buffers of all video players. |
| buffer filling rate | The ratio between the playback time and the download time. |
| connection type | The type of the current devices. |
| content request response time | The elapsed time since the players request for content until the first body chunk of the requested content is delivered to the player (milliseconds). |
| dropped frames | The number of dropped frames reported by all players. |
| operating system | The name of the operating systems of all devices. |
| platform | The name of the platforms of the current devices. |
| rebuffering | The ratio between the rebuffering duration and the actual duration of video played. |
| throughput | The amount of data downloaded during the reporting window. |
API key¶
Every endpoint of the Stats API is authenticated via API key. The API key must be sent as an HTTP header in each request.
Authorization: <API key here>
This API key is specific for the Stats API. Each user is limited to a finite number of requests per second which depends on its customer plan. The API key to be used is labelled as APIS and you will find it in the corresponding section of the Dashboard. For more information, please contact support.
Available Filters¶
Time¶
All data returned by the Stats API is aggregated in different time windows and these aggregations can be requested using the right filter. Below are the available time filters:
- live: Time aggregation window of 5 seconds
- 10m: Time aggregation window of 10 minutes
- 1h: Time aggregation window of 1 hour
- 24h: Time aggregation window of 1 day
- 1w: Time aggregation window of 1 week
- 1M: Time aggregation window of 1 month
- 2M: Time aggregation window of 2 months
- CM: Time aggregation window of the current month
- LM: Time aggregation window of last month
Examples:
http://<REGION>.s73cloud.com/public/api/v3/stats/throughput/agg?time=live
http://<REGION>.s73cloud.com/public/api/v3/stats/throughput/agg?time=10m
<REGION> can be either "emea" or "americas" based on the geographical location of your account. 1
Source¶
Some endpoints can be filtered by source, this means choosing between CDN or peer-to-peer(P2P) data.
- cdn: information related to data downloaded from the CDN.
- p2p: information related to data relayed over the peer-to-peer network.
Examples:
http://<REGION>.s73cloud.com/public/api/v3/stats/throughput/agg?time=10m&source=cdn
http://<REGION>.s73cloud.com/public/api/v3/stats/throughput/agg?time=10m&source=p2p
<REGION> can be either "emea" or "americas" based on the geographical location of your account. 1
Client Errors¶
Below you will find all client errors that might be returned by the Stats API.
400 Bad Request¶
Not sending the required query parameter for each endpoint will result in a 400 Bad Request response. Example of body response:
{
"error": {
"status_code": 400,
"msg": "Bad Request",
"verbose": "Missing query param <time> in request.",
"extra": "Request public/api/v3/summary"
}
}
Sending a wrong value in the query parameters will result in a 400 Bad Request response. Example of body response:
{
"error": {
"status_code": 400,
"msg": "Bad Request",
"verbose": "Wrong format in query param <source> in request.",
"extra": "Request public/api/v3/summary"
}
}
401 Unauthorized¶
Sending an authorization header without permissions to access the API will result in a 401 Unauthorized response. The responses with this status code do not have a body.
403 Forbidden¶
403 Forbidden will be received when performing the following actions:
- Not sending the authorization header will result in a 403 Forbidden response.
- Sending an invalid authorization header will result in a 403 Forbidden response.
The responses with this status code do not have a body.
404 Not Found¶
Doing a request to a URL that does not exist will result in a 404 Not Found response. Example of body response:
Error: Requested URL public/api/v3/dummy_url not found
429 Too Many Requests¶
Exceeding the API key limit of requests per second will result in a 429 Too Many Requests response. Responses with
this status code do not have a<body>.