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 Metrics v3 API Getting Started page for examples of how the API works.
Get Started
This section takes you from zero to your first response. The steps work the same on Windows, macOS, and Linux. You need a command line with curl, which is built into Windows 10 and later, macOS, and most Linux distributions.
Before you begin
- A pair of Conviva API client credentials (an
idand asecret), generated on the Pulse API Management page. Do not use your Pulse login credentials. - The base URL
https://api.conviva.com/insights/3.0. The API accepts HTTPS only.
Keep your credentials secure: Do not type your id and secret directly into a command. Anything on the command line is saved to your shell history, is visible to other users in the process list, and often ends up in CI logs. Base64 is encoding, not encryption, so a base64-encoded credential is no safer. Store credentials in the file described below (or in your CI secret store), never commit a credential file to version control, and rotate them if they are ever exposed.
Step 1: Store your credentials
Create a netrc file so your secret never appears in a command. curl reads it automatically with the --netrc option, which keeps the request commands below identical on every platform.
- macOS and Linux: create
~/.netrc, then restrict it withchmod 600 ~/.netrc. - Windows: create
%USERPROFILE%\_netrc(an underscore, no leading dot).
Add the following, replacing the placeholders with your credentials:
machine api.conviva.com
login YOUR_CLIENT_ID
password YOUR_CLIENT_SECRETBy default curl looks for the netrc file in your home directory. To keep it with a project instead, save it as ./.netrc in your working directory and add --netrc-file ./.netrc to each command. If you do, add .netrc to your .gitignore so the file is never committed to version control.
Prefer environment variables? Set CONVIVA_CLIENT_ID and CONVIVA_CLIENT_SECRET, then pass them with -u. The syntax depends on your shell:
- bash or zsh (macOS, Linux):
curl -u "$CONVIVA_CLIENT_ID:$CONVIVA_CLIENT_SECRET" ... - PowerShell (Windows):
curl.exe -u "${env:CONVIVA_CLIENT_ID}:${env:CONVIVA_CLIENT_SECRET}" ...(usecurl.exe; plaincurlis an alias for Invoke-WebRequest) - Command Prompt (Windows):
curl -u "%CONVIVA_CLIENT_ID%:%CONVIVA_CLIENT_SECRET%" ...
Step 2: Make your first request
Retrieve the attempts metric for the last day. This command is identical on every platform:
curl --netrc "https://api.conviva.com/insights/3.0/metrics/attempts?days=1"What each part does:
attemptsis the metric name and is part of the URL path. Replace it with any key from the Metrics reference.days=1is a query parameter that sets the time range to the last 24 hours. See Time Range for other options.
Step 3: Read the response
The response is time-series JSON. Each entry in time_series is one interval with a timestamp and the metric value, and total summarizes the whole range:
{
"time_series": [
{
"timestamp": {
"epoch_ms": 1663794000000,
"iso_date": "2022-09-21T21:00:00.000Z"
},
"attempts": {
"count": 11830
}
}
],
"total": {
"attempts": {
"count": 141072
}
}
}| Field | Description |
|---|---|
time_series | Array of interval results, one entry per granularity bucket in the requested range. |
time_series[].timestamp.epoch_ms | Interval start time as a Unix epoch in milliseconds. |
time_series[].timestamp.iso_date | The same interval start time in ISO 8601 format. |
time_series[].{metric}.count | The metric value for that interval. The key matches the metric you requested (here, attempts). |
total.{metric}.count | The value aggregated across the entire requested time range. |
Focus on: time_series[].{metric}.count for the value in each interval, and total.{metric}.count for the whole range. Some metrics add fields such as per_unique_device alongside count.
Try other metrics
The same request shape works for every metric. A couple to try:
A quality ratio, Rebuffering Ratio, returned as a percentage:
curl --netrc "https://api.conviva.com/insights/3.0/metrics/rebuffering-ratio?days=1"The headline KPI, Streaming Performance Index. SPI-based metrics accept a kpi_id that selects the threshold set, where kpi_id=1 is Conviva Good:
curl --netrc "https://api.conviva.com/insights/3.0/metrics/streaming-performance-index?days=1&kpi_id=1"Find every available metric, grouped by category with definitions, in the Metrics reference.
Endpoints
| Endpoint | Use it to |
|---|---|
GET /insights/3.0/metrics/{metric_name} | Retrieve one metric over time. |
GET /insights/3.0/metrics/custom-selection?metric=...&metric=... | Retrieve up to 12 metrics in a single call. |
GET /insights/3.0/metrics/{metric_name}/group-by/{dimension} | Break a metric down by a dimension, such as device or city. |
GET /insights/3.0/real-time-metrics/{metric_name} | Retrieve the most recent minutes of data in near real-time. |
The Metrics V3 API enforces per-account request rate limits. See Rate Limits for the current values.
Conviva API system accepts only API client-based credentials. Generate API credentials in the Pulse API Management page.
Note: Let curl build the HTTP Basic Authorization header for you from a stored credential rather than base64-encoding it by hand on the command line. See Get Started for the --netrc setup, and the Authentication page for the header format.
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-selectionendpoint. - 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:
| Parameter Name | Path / Query | Default Value |
|---|---|---|
| metric or custom-selection | Path | - |
| group-by dimension | Path | - |
| time range | Query |
|
| granularity | Query |
|
| filter(s) | Query | All Traffic filter (no filtering logic applied) |
| KPI threshold | Query | kpi_id=1 i.e. Conviva Good |
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=5To 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-playsEach ?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: Group-by dimension identifiers are kebab-case, for example device-os (Device Operating System) and geo-city-name (Cities). Retrieve the full list from the /insights/3.0/metrics/_meta/references/dimensions endpoint. Filter query parameters use the underscore form, for example device_os.
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:00ZCustom 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:00ZDimension 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=50Summary
{
"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:00ZSorting 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_byquery parameter to indicate the metric for sorting. - use the
?orderquery parameter to indicate the direction (descorasc).
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=descThis 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:ssZto specify thestart_dateandend_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:00ZUsing 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=1641096000Use 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
?daysquery 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=PT6HDefault 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=AndroidFiltering 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=AndroidLogical 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=mxwhich 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=cais 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=9876543210KPI 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=2Rate Limits
Access limits are enforced per c3 account as queries per minute (QPM). Analytical query limits are shared across all analytical endpoints, including Historical Metrics V3 and Sessions V3. Requests that exceed a limit receive an HTTP 429 (Too Many Requests) response. The default limits are:
| Query type | Endpoint | Default limit |
|---|---|---|
| Real-Time Metrics V3 | /insights/3.0/real-time-metrics | 60 QPM per c3 account |
| Historical Metrics V3 (last 30 days) | /insights/3.0/metrics | 30 QPM per c3 account (shared across all analytical queries) |
| Historical Metrics V3 (beyond last 30 days) | /insights/3.0/metrics | 15 QPM per c3 account (shared across all analytical queries) |
Note: These are the default rate limits. Your account's limit may differ; contact Conviva to confirm the limits for your c3 account.
Type to search. Results appear as you type.