Metrics V3 API User Guide

The Conviva Metrics V3 API provides programmatic access to the historical and real-time metrics. Use Conviva data to build custom dashboards or applications.

While using this API, refer to the Getting Started page for examples of how the API works.

Access limits for Conviva APIs, per minute for each c3 account. Rate limits are based on the number of requests and applied filters. A 500 concurrent request limit is reached with either 100 requests with 5 filters or 500 requests with 1 filter.

Conviva API system accepts only API client-based credentials. Generate API credentials in the Pulse API Management page.

Note: To encode API credentials to Base64 format, enter the prompt in the command line:
echo -n "{client_id}:{client_secret}" | base64
(replace {client_id} and {client_secret} with the API credentials of the c3 account)

Do not use Pulse user-based credentials for any API request.

Key Features of Metrics V3

The Metrics V3 API adds support for several new features for improved data retrieval.

• Retrieve data of a single metric using .../{metric_name}.
• Retrieve data from combinations of related metric endpoints using the .../custom-selection endpoint.
• Retrieve metric values for specific predefined dimensions, such as device operating system and city, using .../group-by/{dimension_name}.
• Retrieve metric values for custom dimensional tags using .../group-by/dimension-tag/{custom_tag}.

For Metrics V3 APIs, the response payload size is limited to 5700000 bytes. If a response body exceeds the limit, get the HTTP 413 status Request Entity Too Large.

API Parameters

All Metrics V3 API requests are HTTP GET requests. To retrieve data, specify the following parameters in the request:

API request paths for historical and real-time metrics:

Historic Merics

insights/3.0/metrics/...

For example: GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5

Real-Time Metrics

insights/3.0/real-time-metrics/...

For example, GET https://api.conviva.com/insights/3.0/real-time-metrics/attempts

This user guide considered Historical metrics for all the API sample requests. To retrieve the corresponding real-time metrics, simply replace .../metrics/... with .../real-time-metrics/....

Metrics

Metrics V3 API supports fetching data for over 70 individual metrics as separate metric values by using .../{metric_name}, or multiple singular metrics in a request using custom-selection.

Example of Retrieving a Single Metric

The following request retrieves data of the attempts metric.

GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5

To return data of a metric, first identify the desired metric name and specify the date range.

GET /3.0/metrics/{metric_name}?{start_date}&{end_date}

where {metric_name} is one of the names defined on the Metrics page.

Retrieving Multiple Singular Metrics in a Request

It is also possible to custom-select multiple singular metrics in one request.

Use the custom-selection endpoint to select up to a maximum of 12 singular metrics in one request.

GET /3.0/metrics/custom-selection?metric={metric_name_1}&metric={metric_name_2}&metric={metric_name_3}&{start_date}&{end_date}

Use the ?metric query parameter to indicate the singular metric to select.

The functionality of this endpoint is similar to SQL SELECT {column1},{column2},{column3} statement, where each ?metric query parameter is equivalent of a column name. Similarly, the custom-selection endpoint is the API equivalent of the metrics selection UI feature on Pulse.

Example

The following request retrieves data of the attempts, bitrate, and concurrent-plays metrics.

GET https://api.conviva.com/insights/3.0/metrics/custom-selection?days=5&metric=attempts&metric=bitrate&metric=concurrent-plays

Each ?metric query parameter accepts only a single metric name. Find the list of available metric names in the Metrics page.

Dimensions

Conviva applications support grouping of metric data based on a selected dimension, and then return metrics for each dimensional entity. For example, the City dimension can have entities for New York and San Francisco.

Metrics V3 supports dimensions for API data. This is similar to SQL GROUP BY statement, where data is grouped by a specific column (i.e. dimension), and calculation is aggregated upon each group.

To retrieve metric data grouped by a dimension:

GET /3.0/metrics/{metric_name}/group-by/{dimension}?{start_date}&{end_date}

Here, {dimension} is the name of the dimension for grouping. See the predefined Dimensions page to find the list of supported dimensions.

Note: Dimensions are configured during the sign-up and integration with Conviva. Not all predefined dimensions may be available for the c3 account.

Contact Conviva Support (support@conviva.com) to add more dimensions to the c3 account. In addition, programmatically retrieve a list of group-by dimensions via an endpoint.

Use group-by to get the list of available group-by dimensions.

Example

The following request retrieves attempts metric data that is grouped by the isp dimension:

GET https://api.conviva.com/insights/3.0/metrics/attempts/group-by/isp?start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T04:00:00Z

Custom Dimensions (Custom Tags)

In addition to the dimensions defined by Conviva, Conviva also supports defining other dimensions specific to the c3 account. These dimensions are known as custom tags.

To retrieve metric data grouped by a custom-tag dimension:

GET /3.0/metrics/{metric_name}/group-by/dimension-tag/{custom_tag_dimension}?{start_date}&{end_date}

where {custom_tag_dimension} is the name of the custom tag.

In addition, programmatically retrieve a list of group-by custom-tag dimensions via an endpoint. Use dimension-tag to get a list of custom tags defined for the c3 account.

GET https://api.conviva.com/insights/3.0/metrics/attempts/group-by/dimension-tag?start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T04:00:00Z

Dimension Entities limit

GET /3.0/metrics/attempts/group-by/asset?start_date=2022-07-19T21:00:00.000Z&end_date=2022-07-19T23:00:00.000Z&limit=50

Summary

{
  "time_series": [
    {
      "timestamp": {
        "epoch_ms": 1658264400000,
        "iso_date": "2022-07-19T21:00:00.000Z"
      },
      "dimensional_data": [
        {
          "dimension": {
            "key": "asset",
            "value": "TV Series S01E01"
          },
          "metrics": {
            "attempts": {
              "count": 173653
            }
          }
        },
        {
          "dimension": {
            "key": "asset",
            "value": "TV Series S01E02"
          },
          "metrics": {
            "attempts": {
              "count": 142286
            }
          }
        }

        // ... and more
      ]
    }
  ]
}

In a group-by response, metrics data of each granular interval are grouped by dimension entities (as key and value), and they are returned in a dimensional_data array.

By default, the dimensional_data array size is capped at maximum 50 items; hence, the request returns the top 50 dimensional entities.

To overwrite the defaut value, specify the cap limit using the limit query param. The parameter expects a non-negative integer value, up to a maximum of 500.

High limit value implies fetching more data. To protect our system, when the value is greater than the default 50, the time range is restricted to a maximum of 24 hour range.

For example, GET 3.0/metrics/attempts/group-by/asset?limit=500&days=3 is an invalid request, as the time range days=3 has a length of beyond 24 hours.

Example

GET https://api.conviva.com/insights/3.0/metrics/attempts/group-by/asset?limit=100&start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T04:00:00Z

Sorting by a Metric in a Group-by Request

When retrieving multiple metrics grouped by a dimension, specify a metric for sorting. Also, retrieve data in ascending or descending order.

In a /group-by/{dimension} request:

• use the ?sort_by query parameter to indicate the metric for sorting.
• use the ?order query parameter to indicate the direction (desc or asc).

Example

GET https://api.conviva.com/insights/3.0/metrics/custom-selection/group-by/asset?days=5&metric=attempts&metric=bitrate&metric=concurrent-plays&sort_by=concurrent-plays&order=desc

This is the API equivalent of the sorting feature in the Metric Lens page on Pulse. The ?sort_by query parameter accepts only a single metric name.

Find the list of available metric names in the Singular Metrics section of the Metrics page.

Time Series

The data returned in the Metrics V3 APIs is time-series data. The API calls must specify a time range and an interval granularity.

Time Range

To retrieve metric data, every API request needs a time range and specify that in query parameters. Use one of the predefined Time Range formats to specify a time range.

• Use only one time-range format per request.
• Use ISO 8601 date-time format YYYY-MM-DDTHH:mm:ssZ to specify the start_date and end_date.

Examples

Using Date-Time Format

The following request retrieves attempts historical metric data of a time range (from 2022-01-01T04:00:00Z to 2022-01-02T04:00:00Z) using ISO 8601 date-time format:

GET https://api.conviva.com/insights/3.0/metrics/attempts?start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T04:00:00Z

Using Unix Epoch Time Format

The following is the same request that retrieves attempts metric data of the time range using epoch time format:

GET https://api.conviva.com/insights/3.0/metrics/attempts?start_epoch=1641009600&end_epoch=1641096000

Use start_epoch_ms and end_epoch_ms for epoch time in milliseconds.

Using Last N days for Historical Metrics

The following request retrieves attempts historical metric data of the last 5 days (from the most recent clock hour):

GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5

• Historical metric data has a maximum time range of 90 days within the last 13 months.
• Real-Time metric data has a maximum time range of 15 minutes.
• For real-time metrics endpoints, the ?days query parameter has been replaced by ?minutes.

For more details about the time range, see Time Range.

Interval Granularity

Time series data is returned according to time intervals. Use the granularity query parameter to specify the interval granularity.

See the Granularity options page for the list of supported granularity options.

Example

The following request retrieves attempts metric data with an interval granularity of every 6 hour:

GET https://api.conviva.com/insights/3.0/metrics/attempts?start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T04:00:00Z&granularity=PT6H

Default Time Series Parameters

If an interval granularty is not specified in a request, the system by default assumes granularity=PT1H (per 1 hour) for historical metrics and granularity=PT1M (per 1 minute) for real-time metrics.

Filtering by Dimensions

These APIs support filtering by various dimensions (predefined by Conviva, as well as custom tags). To retrieve a complete list of filtering dimensions available for the c3 account, use the look-up endpoint of listing available Dimensions.

Use query parameters to specify dimensional filters, and multiple dimensions in a request.

Note A request with multiple filters of different dimensions implies that the filters are joined with a logical AND.

A request with multiple filters of same dimension implies that the filters are joined with a logical OR.

Filtering by Conviva-Defined Dimensions

See pre-defined Dimensions page to find the list of supported filtering dimensions defined by Conviva.

Example

The following API request retrieves attempts metric data with the geo_city_name (city of Los Angeles, CA) and device_os (Android OS) filters:

GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5&geo_city_name=Los Angeles, California, United States&device_os=Android

Filtering by Custom Dimension Tags (prefix tag_)

In addition to the predefined dimensions, it's also possible to filter by custom dimension tags. Append the prefix tag_ to the tag name, and use that as the query parameter key.

Example

Assuming that c3 account has a custom dimension tag called specialContentId. Filter by that dimension using tag_specialContentId as the query paramter key.

GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5&tag_specialContentId=1A2B3C4D5E&device_os=Android

Logical OR Filtering of the Same Dimension

Metrics V3 API supports OR filtering of the same dimension. For example, retrieving metric data of multiple countries combined together.

Repeat the same dimension query parameter multiple times, such as:

GET /3.0/metrics/attempts?days=5&geo_country_code=us&geo_country_code=ca&geo_country_code=mx

which is translated to geo_country_code=usORgeo_country_code=caORgeo_country_code=mx.

In conjunction with multi-dimension AND filtering, a query like:

?device_os=Android&device_os=iOS&geo_country_code=us&geo_country_code=ca

is translated to the following SQL logic

WHERE
  (device_os = 'Android' OR device_os = 'iOS')
  AND
  (geo_country_code = 'us' OR geo_country_code = 'ca')

Limitation

Logical OR only works for filtering of the same dimension.

OR filtering of different dimensions is considered complex logic. For example, the combination of device_name=Android Phone OR geo_country_code=us is not possible. For complex logic, create a saved filter and apply it with filter_id.

Dimension entity values can contain commas, so we do not support comma-separated list.

geo_country_code=us,ca,mx is interpreted as a single string "us,ca,mx".

Filtering by a Saved Filter filter_id

Conviva offers saved filters for complex filtering logic. For example, mixing AND, OR, NOT, and so on.

Create a filter using the Filter Management page on Pulse or via Bulk Filter API.

Each saved filter has a unique identifier (that is, filter id). In the API request, apply the saved filter using the filter_id query parameter and specify the id as the query value.

The filter_id query parameter is singular and expects only one id value. Thus, maximum one saved filter per request.

A request can only have one type of filter, either a saved filter (filter_id) or a combination of dimensional filters, but not both types. Thus, saved filters and dimensional filters are exclusive OR of each other.

When filter_id is used, the request cannot have any dimensional filters.

Example

Assume the c3 account has a saved filter with id 9876543210. Apply the filter using filter_id as the query parameter key:

GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5&filter_id=9876543210

KPI Thresholds kpi_id

Some metrics (such as Streaming Performance Index or Improvement Opportunities) are calculated based on a set of custom thresholds. The set of thresholds is known as KPI.

Use the GET /kpis endpoint to retrieve a list of KPI metadata (kpi_id and kpi_name).

When retrieving metric data, use the kpi_id query parameter to specify which set of KPI to use for calculation.

When the kpi_id query parameter is omitted, the system by default assumes "Conviva Good", which is an equivalent of kpi_id=1.

Example

GET https://api.conviva.com/insights/3.0/metrics/attempts?days=5&kpi_id=2

Metrics V3 API Metrics V3 API Metrics V3 API