Endpoints¶

The Edge Analytics API is a versioned JSON API which endpoints are organized into two main groups:

v1/: grouping all the new metrics endpoints along with the query endpoint.
legacy/: containing all endpoints ported from the Legacy Stats API to ease the migration to the Edge Analytics API. Please find the Legacy endpoints reference here.

This section of the documentation will focus on the new set of endpoints (under v1/) because the legacy set of endpoints inherit the interface from the Legacy Stats API.

API base URL: https://api.system73.com/analytics

Remember

The API swagger/OpenAPI reference is available on https://api.system73.com/analytics/docs/.

Metrics endpoints (`v1/metrics/`)¶

This set of endpoints share the same interface and capabilities as all of them provide a metric and allow you to filter the results with predefined set of filters.

Request body¶

Filter	Type	Default	Description
from_date	string		The start date and time of the query in ISO-8601 format
to_date	string		The end date and time of the query in ISO-8601 format
source	string		The stream source query filter
channel_id	string		The stream channel ID query filter
bitrate	string		The stream bitrate query filter
stream_id	string		The stream ID query filter
stream_uri	string		The stream URI query filter
stream_state	string		The stream state query filter (Any of: `live`, `vod`, `dvr`, `unknown`)
representation_id	string		The stream representation ID query filter
granularity	string	`second`	The granularity of the query (Any of: `second`, `minute`, `fifteen_minute`, `thirty_minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`)
approximate_count_distinct	boolean	`true`	Enable or disable the approximate algorithm on the distinct count aggregator
target_customer_id	string		Override the customer ID of the query (reseller users only)

Time interval¶

You must specify the timeframe of the metric to be calculated with the parameters from_date and to_date. The time boundaries are strings containing a date and time in the ISO-8601 format with a precision of up to seconds. Microseconds are truncated from the input.

Valid inputs

"2012-01-01T10:12:30.000Z"
"2012-01-01T10:12:30"

Query filters¶

You can filter metrics results by the following properties:

These filters are optional and any filter combination can be applied.

Granularity¶

You can choose any query granularity from the list of supported granularities:

second
minute
fifteen_minute
thirty_minute
hour
day
week
month
quarter
year

However, depending on the data layer you have the following restrictions:

Realtime: you can use from second to thirty_minute for time intervals of up to 48h.
Historical: the finest supported granularity is minute because of the historical datasources characteristics.

Approximate count distinct ¶

Important

This parameter is only available to the Advanced tier customers, while Lite customers are restricted to the default behavior.

This filter determines whether to apply an approximate count distinct aggregation or a precise one. By default, it is set to true (approximate aggregation). This parameter has a great impact on the performance of queries that scan a large number of rows.

The optional approximate_count_distinct field in the request body has no effect unless the underlying query involves a SQL COUNT(DISTINCT foo) statement.

The following is a list of metrics endpoints where this filter applies:

/v1/metrics/audience/asn
/v1/metrics/audience/connection_types
/v1/metrics/traffic/asn
/v1/metrics/traffic/asn/percentage

Target Customer ID¶

Important

The parameter is only available for reseller users. It does not have any effect when used as a non-reseller user.

The optional target_customer_id field allows reseller users to specify which of their customers to perform the query on. As a reseller, you are only permitted to query data for customers within your account. Any attempt to query data for customers outside your customer list will result in an authorization error.

Query endpoint (`v1/query/sql`)¶

This endpoint allows you to get metrics from custom SQL queries with the constructs supported by the Druid SQL dialect. In general, this dialect offers much of the same functionality you can get from traditional relational databases but it is highly recommended to read the linked documentation so you get more familiar with Druid specifics.

Requirements¶

Additionally, there is a series of restrictions that need to be followed in order to produce valid queries:

Schema fields

You can only reference datasource fields belonging to your Analytics tier. Check the Schema section of the Data Model for more information.
Example

A customer in the Lite tier cannot issue the following query because the field ConnectionType belongs to the Advanced tier.
```
SELECT TIME_FLOOR(__time, 'PT1M') AS "timestamp", AVG(BufferHealth) as "avg_buffer_health"
FROM "sdk-emea-realtime"
WHERE CustomerId = '1234' AND ConnectionType = 'ETHERNET'
    AND __time >= '2022-12-30' AND __time < '2022-12-31'
GROUP BY 1
```
Note

The use of SELECT * statement over EI datasources is allowed with certain restrictions.
CustomerId and region

Queries must always filter by your assigned CustomerId.

Also, you need to select the datasource that corresponds to your data deployment region.
Example
```
SELECT TIME_FLOOR(__time, 'P1D') AS "timestamp", AVG(BufferHealth) as "avg_buffer_health"
FROM "sdk-americas-historical-hour"
WHERE CustomerId = '1234'
    AND __time >= '2022-01-01T00:00:00' AND __time < '2022-04-01T00:00:00'
GROUP BY 1
```
Info

You can find your corresponding CustomerId and region on the Platform's Account Settings section (under the Account Details tab).

Restrictions¶

Select-star queries¶

SELECT * queries are allowed as long as you include a LIMIT clause that is subject to a restriction on the maximum number of rows depending on your Analytics Tier:

Tier	Max rows
Lite	1,000 rows
Advanced	10,000 rows

Example

SELECT *
FROM "sdk-americas-historical-hour"
WHERE CustomerId = '1234'
LIMIT 50

Query context¶

You can use the query context to customize query execution/planning. However, the following flags has some restrictions.

useApproximateCountDistinct: Users on the Lite data tier cannot modify this flag. The default value is true.

Best practices¶

As in other big data solutions, the following recommendations will help making the most out of the queries while ensuring acceptable performance levels and resource usage:

Avoid queries including too many fields or SELECT * queries.
Always include a filter for __time to limit the amount of data than needs to be scanned.
Avoid queries spanning large intervals of time (e.g., >48h) on realtime datasources.
Avoid fine granularities on large time interval queries.
Try to avoid subqueries underneath joins: they affect both performance and scalability.

Legacy endpoints (`legacy/stats/`)¶

Overview¶

This legacy section of the Edge Analytics provides summarized statistics of the system like P2P or CDN throughput, buffer health, buffer filling rate, and more.

Data is provided by the customer, and can be filtered by channel and stream, and some endpoints can also be filtered by bitrate.

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.
Dropped frames	The number of dropped frames reported by all players.
Operating system	The name of the operating systems of all devices.
Platforms	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.

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:

https://api.system73.com/analytics/legacy/stats/throughput/agg?time=live
https://api.system73.com/analytics/legacy/stats/throughput/agg?time=10m

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:

https://api.system73.com/analytics/legacy/stats/throughput/agg?time=10m&source=cdn
https://api.system73.com/analytics/legacy/stats/throughput/agg?time=10m&source=p2p

Summary¶

`/summary`¶

Method: GET

Description

Provides information about customer's channels such as throughput, devices and viewing time of each one. The throughput unit is kbps_ and the viewing time is in _seconds. The endpoints can be paginated using the appropriate query parameters.

Required parameters:

time=[time filters]

Success Response:

200 OK

[
   {
       "channel_id": [string],
       "cdn_throughput": [numeric],
       "p2p_throughput": [numeric],
       "total_throughput": [numeric],
       "cdn_devices": [numeric],
       "p2p_devices": [numeric],
       "not_compatible_devices": [numeric],
       "cdn_viewing_time": [numeric],
       "p2p_viewing_time": [numeric],
       "total_viewing_time": [numeric],
       "total_pretty_viewing_time": [string]
   },
   { ... }
]

Call samples:

/summary?time=live
/summary?time=24h

Sample Response

[
   {
      "channel_id": "1",
      "cdn_throughput": 40000,
      "p2p_throughput": 180000,
      "total_throughput": 220000,
      "cdn_devices": 2,
      "p2p_devices": 9,
      "not_compatible_devices": 0,
      "cdn_viewing_time": 10,
      "p2p_viewing_time": 45,
      "total_viewing_time": 55,
      "total_pretty_viewing_time": "0:00:55"
   },
   { ... }
]

`/summary/agg`¶

Method: GET

Description

Provides aggregated information depending on the endpoint such as throughput, devices and viewing time. The throughput unit is kbps and the viewing time is in seconds.

Required parameters:

time=[time filters]

Success Response:

200 OK

[
   {
      "aggregate": [string],
      "cdn_throughput": [numeric],
      "p2p_throughput": [numeric],
      "total_throughput": [numeric],
      "cdn_devices": [numeric],
      "p2p_devices": [numeric],
      "not_compatible_devices": [numeric],
      "cdn_viewing_time": [numeric],
      "p2p_viewing_time": [numeric],
      "total_viewing_time": [numeric],
      "total_pretty_viewing_time": [string]
   },
   { ... }
]

Call samples:

/summary/agg?time=live
/summary/agg?time=24h

Sample Response

[
   {
      "aggregate": "aggregate",
      "cdn_throughput": 40000,
      "p2p_throughput": 180000,
      "total_throughput": 220000,
      "cdn_devices": 2,
      "p2p_devices": 9,
      "not_compatible_devices": 0,
      "cdn_viewing_time": 10,
      "p2p_viewing_time": 45,
      "total_viewing_time": 55,
      "total_pretty_viewing_time": "0:00:55"
   }
]

System Statistics¶

`/stats/throughput/agg`¶

URLs:

/stats/throughput/agg
/channels/{channel_id}/stats/throughput/agg
/channels/{channel_id}/streams/{stream_id}/stats/throughput/agg

Method: GET

Description

Provides information about the aggregated throughput for a customer, specific channel or stream. Throughput unit is kbps.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "agg_throughput_{source}": [numeric]
   },
   { ... }
]

Call example:

/throughput/agg?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "agg_throughput_cdn": 1.0
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/buffer_health/avg`¶

URLs:

/stats/buffer_health/avg
/channels/{channel_id}/stats/buffer_health/avg
/channels/{channel_id}/streams/{stream_id}/stats/buffer_health/avg

Method: GET

Description

Provides information about the average buffer health for a customer or specific channel. Buffer health unit is milliseconds.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "avg_buffer_health_{source}": [numeric]
   },
   { ... }
]

Call example:

/buffer_health/avg?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "avg_buffer_health_cdn": 228212.0
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/rebuffering/ratio`¶

URLs:

/stats/rebuffering/ratio
/channels/{channel_id}/stats/rebuffering/ratio
/channels/{channel_id}/streams/{stream_id}/stats/rebuffering/ratio

Method: GET

Description

Provides information about the rebuffering ratio for a customer or specific channel.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "rebuffering_ratio": [numeric]
   },
   { ... }
]

Call example:

/rebuffering/ratio?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "rebuffering_ratio": 0.1
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/buffer_filling_rate/avg`¶

URLs:

/channels/{channel_id}/stats/buffer_filling_rate/avg
/channels/{channel_id}/streams/{stream_id}/stats/buffer_filling_rate/avg

Method: GET

Description

Provides information about the average buffer filling rate for a specific channel.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "avg_buffer_filling_rate_{source}": [numeric]
   },
   { ... }
]

Call example:

/buffer_filling_rate/avg?time=live&source=cdn

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "avg_buffer_filling_rate_cdn": 3.4
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/dropped_frames/avg`¶

URLs:

/channels/{channel_id}/stats/dropped_frames/avg
/channels/{channel_id}/streams/{stream_id}/stats/dropped_frames/avg

Method: GET

Description

Provides information about the average dropped frames for a specific channel.

Required parameters:

time=[time filters]
source=[source filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "avg_dropped_frames_{source}": [numeric]
   },
   { ... }
]

Call example:

/dropped_frames/avg?time=live&source=p2p

Sample Response

[
   {
       "datetime": 1686667767000.0,
       "avg_dropped_frames_p2p": 0
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

Devices Statistics¶

`/stats/os`¶

URLs:

/stats/os
/channels/{channel_id}/stats/os
/channels/{channel_id}/streams/{stream_id}/stats/os

Method: GET

Description

Provides information about the operating systems and the number of devices of each one for a customer or specific channel.

Required parameters:

time=[time filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "operating_systems": [object]
   },
   { ... }
]

Call example:

/os?time=live

Sample Response

[
   {
       "datetime": 1686649896000.0,
       "operating_systems": {
           "MAC_OS": 1,
           "LINUX": 2,
           "WINDOWS": 1
      }
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/platforms`¶

URLs:

/stats/platforms
/channels/{channel_id}/stats/platforms
/channels/{channel_id}/streams/{stream_id}/stats/platforms

Method: GET

Description

Provides information about the platforms and the number of devices of each one for a customer or specific channel.

Required parameters:

time=[time filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "platforms": [object]
   },
   { ... }
]

Call example:

/platforms?time=live

Sample Response

[
   {
       "datetime": 1686650018000.0,
       "platforms": {
           "FIREFOX": 1,
           "CHROME": 2,
           "EDGE": 1
      }
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

`/stats/connection_types`¶

URLs:

/stats/connection_types
/channels/{channel_id}/stats/connection_types
/channels/{channel_id}/streams/{stream_id}/stats/connection_types

Method: GET

Description

Provides information about the connection types and the number of devices of each one for a customer or specific channel.

Required parameters:

time=[time filters]

Optional parameters:

bitrate=[string]
representation_id=[string]

Success Response:

200 OK

[
   {
      "datetime": [timestamp],
      "connection_types": [object]
   },
   { ... }
]

Call example:

/connection_types?time=live

Sample Response

[
   {
       "datetime": 1686650123000.0,
       "connection_types": {
           "ETHERNET": 1,
           "WIFI": 2,
           "CELLULAR": 1
      }
   }
]

Note

bitrate and representation_id query param only apply to the stream filtered endpoint.

Client Errors¶

Below you will find the client errors that might be returned by the 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:

{
    "detail": [
        {
            "loc": [
                "query",
                "time"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

Sending a wrong value in the query parameters will result in a 400 Bad Request response. Example of body response:

{
    "detail": [
      {"loc": [
        "query",
        "source"
      ],
        "msg": "value is not a valid enumeration member; permitted: 'cdn', 'p2p'",
        "type": "type_error.enum",
        "ctx": {
          "enum_values": [
            "cdn",
            "p2p"
          ]
        }
      }
    ]
}

401 Unauthorized¶

401 Unauthorized will be received when performing the following actions:

Not sending the authorization header will result in a 401 Unauthorized response.
Sending an invalid authorization header will result in a 401 Unauthorized response.

{
  "type": "not-authenticated",
  "title": "Not authenticated"
}

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:

{
  "detail": "Not Found"
}

This section was last updated 2024-12-19

Endpoints¶

Metrics endpoints (v1/metrics/)¶

Request body¶

Time interval¶

Query filters¶

Granularity¶

Approximate count distinct ¶

Target Customer ID¶

Query endpoint (v1/query/sql)¶

Requirements¶

Restrictions¶

Select-star queries¶

Query context¶

Best practices¶

Legacy endpoints (legacy/stats/)¶

Overview¶

Exposed Metrics¶

Available Filters¶

Time¶

Source¶

Summary¶

/summary¶

/summary/agg¶

System Statistics¶

/stats/throughput/agg¶

/stats/buffer_health/avg¶

/stats/rebuffering/ratio¶

/stats/buffer_filling_rate/avg¶

/stats/dropped_frames/avg¶

Devices Statistics¶

/stats/os¶

/stats/platforms¶

/stats/connection_types¶

Client Errors¶

400 Bad Request¶

401 Unauthorized¶

404 Not Found¶

Metrics endpoints (`v1/metrics/`)¶

Query endpoint (`v1/query/sql`)¶

Legacy endpoints (`legacy/stats/`)¶

`/summary`¶

`/summary/agg`¶

`/stats/throughput/agg`¶

`/stats/buffer_health/avg`¶

`/stats/rebuffering/ratio`¶

`/stats/buffer_filling_rate/avg`¶

`/stats/dropped_frames/avg`¶

`/stats/os`¶

`/stats/platforms`¶

`/stats/connection_types`¶