DPI Analytics API - Quick Start Guide

 

Introduction

DPI Analytics API is based on conceptual model of metrics and dimensions. Select a set of metrics, and query data by time-series or group-by a dimension that is available for the c3 account. This API supports both Conviva-defined metrics and custom metrics.

 

The DPI Analytics API works differently conpared to the DPI Flow API:

  • DPI Analytics API query data based on the selection of metrics.

  • DPI Flow API query data based on the selection of flow model.

Note: DPI Analytics API supports retrieving real-time data up to the last 15 minutes, and historical data up to the last 7 days, with a maximum query interval of 1 hour.

DPI Analytics API Endpoints

GET Endpoints
List of metrics and dimensions

https://api.conviva.com/analytics/metadata/data-model
Historical metric data in time series format https://api.conviva.com/analytics/metrics/{selected_metric_keys}/{start_timestamp}_to_{end_timestamp}
Historical metric data in group-by a dimension format https://api.conviva.com/analytics/metrics/{selected_metric_keys}/{start_timestamp}_to_{end_timestamp}/group-by/{group_by_dimension}
Real-time metric data in time series format https://api.conviva.com/analytics/real-time-metrics/{selected_metric_keys}/{relative_time_interval}
Real-time metric data group-by a dimension https://api.conviva.com/analytics/real-time-metrics/{selected_metric_keys}/{relative_time_interval}/group-by/{group_by_dimension}

Analytics API Outline

Retrieve the metrics data in the following sequence:

Note: Few things to remember:
- Analytics API only supports the HTTP GET method.
- Specify all required parameters in the URI path.
- Specify the optional parameters in the query string.

Method

Analytics API supports only https GET method. This method acts like a digital query to retrieve the metrics for a given time range, grouped by a dimension.

API Security

HTTPS ensures that the data remains encrypted and protected from unauthorized access while transmitting between the clients and servers, thereby bolstering overall system security.

Authentication

Conviva API system accepts only API client-based credentials. Generate API credentials client-Id and client-secret from the Pulse API Management page.

While calling the Analytics API, use the generated client-Id and client-secret.

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

Content Type

application/JSON

This API supports the content to be sent and received in the format of JSON data.

Get All Available Metrics and Dimensions

Retrieve the list of metrics and dimensions available for the user's account.

Request

Copy 
https://api.conviva.com/analytics/metadata/data-model

Response

In the response, see the list of available metrics, and dimensions, in JSON format.

Note: Keep the key of metrics and dimensions handy. Specify them in the URI path while analyzing the metrics grouped by a dimension.

Copy 
{
  "metrics": [
    {
      "key": "active_devices",
      "label": "Active Devices",
      "unit": "count",
      "is_conviva_defined": true
    },
    {
      "key": "active_users",
      "label": "Active Users",
      "unit": "count",
      "is_conviva_defined": true
    },
    {
      "key": "page_views",
      "label": "Page Views",
      "unit": "count",
      "is_conviva_defined": true
    },
    {
      "key": "total_events",
      "label": "Total Events",
      "unit": "count",
      "is_conviva_defined": true
    }
    // more metrics
  ],
  "dimensions": [
    {
      "key": "app_id",
      "label": "App Name"
    },
    {
      "key": "browser_name",
      "label": "Browser Name"
    }
    // more dimensions
  ]
}

 

Get Metrics Data in Time Series Format

Retrieve the metrics data in a time series format:

Analyze Real-Time Metric Data in Time Series Format

This section explains how to retrieve real-time metric data in a time series format.

URL

Copy 
https://api.conviva.com/analytics/real-time-metrics/{selected_metric_keys}/{relative_time_interval}

Execute the API with required parameters in URI path:

  • selected_metric_keys: Specify at most 12 metric keys as a comma-separated list in the path parameter. For example, active_devices,active_users,page_views,total_events and so on.

  • relative_time_interval: A relative time interval that returns the last N minutes data. For example, PT1M (one minute data), PT2M (2 minutes data), and so on till PT15M (15 minutes data).

Analyze the metrics, active_devices, active_users, page_views, and total_events with 1 minute interval. Specify the 1-minute interval as a filter criteria in the query srting. For better analysis, slice the last n-minute metric data and use granularity into the response.

Example Request

Copy 
https://api.conviva.com/analytics/real-time-metrics/active_devices,active_users,page_views,total_events/PT5M?granularity=PT1M

Example Response

Copy 
{
  "time_series": [
    {
      "timestamp": {
        "epoch_ms": 1752477117000,
        "iso_date": "2025-07-14T07:11:57.000Z"
      },
      "metric_data": {
        "active_devices": 33155,
        "active_users": 18455,
        "page_views": 1089,
        "total_events": 73709
      }
    },
    {
      "timestamp": {
        "epoch_ms": 1752477177000,
        "iso_date": "2025-07-14T07:12:57.000Z"
      },
      "metric_data": {
        "active_devices": 28114,
        "active_users": 15441,
        "page_views": 1163,
        "total_events": 74914
      }
    }
    // more timestamp metric data sets
  ],
  "aggregated_metric_data": {
    "active_devices": 37897,
    "active_users": 21347,
    "page_views": 2252,
    "total_events": 148623
  }
}

 

Analyze Historical Metric Data in Time Series Format

This section explains how to retrieve historical metric data in a time series format.

URL

Copy 
https://api.conviva.com/analytics/metrics/{selected_metric_keys}/{start_timestamp}_to_{end_timestamp}

Execute the API with required parameters in URI path:

  • selected_metric_keys: Specify at most 12 metric keys as a comma-separated list in the path parameter. For example, active_devices,active_users,page_views,total_events and so on.

  • start_timestamp: The start time of a time interval in epoch ms or ISO 8601 format.

  • end_timestamp: The end time of a time interval in epoch ms or ISO 8601 format.

Note: Remember, the start_timestamp should be earlier than the end_timestamp.

 

Analyze the 30 minutes historical metrics data.

Example Request

Copy 
https://api.conviva.com/analytics/metrics/active_devices,active_users,page_views,total_events/1752468000000_to_1752469800000

Example Response

Copy 
{
  "time_series": [
    {
      "timestamp": {
        "epoch_ms": 1752468000000,
        "iso_date": "2025-07-14T04:40:00.000Z"
      },
      "metric_data": {
        "active_devices": 73045,
        "active_users": 46504,
        "page_views": 15173,
        "total_events": 1128101
      }
    },
    {
      "timestamp": {
        "epoch_ms": 1752469800000,
        "iso_date": "2025-07-14T05:10:00.000Z"
      },
      "metric_data": {
        "active_devices": 101135,
        "active_users": 55588,
        "page_views": 46399,
        "total_events": 2295951
      }
    }
  ],
  "aggregated_metric_data": {
    "active_devices": 145256,
    "active_users": 84699,
    "page_views": 61572,
    "total_events": 3424052
  }
}

 

Get Metrics Data in Group By Dimensions

Retrieve the metric data group by dimension. See the list of dimenstions available for analyzing the metrics.

Each dimension is asigned to a key.
For example,

Copy 
"dimensions": [
    {
        "key": "app_id",
        "label": "App Name"
    },
    {
        "key": "browser_name",
        "label": "Browser Name"
    }
    // more dimensions
]

While executing an API call, specify the dimension key in the URI path.

Let's see:

Real-time Metric Data Group-By a Dimension

This section explains how to use a dimension to group real-time metric data.

URL

Copy 
https://api.conviva.com/analytics/real-time-metrics/{selected_metric_keys}/{relative_time_interval}/group-by/{group_by_dimension}

Execute the API with required parameters in URI path:

  • selected_metric_keys: Specify at most 12 metric keys as a comma-separated list in the path parameter. For example, active_devices,active_users,page_views,total_events and so on.

  • relative_time_interval: A relative time interval that returns the last N minutes data. For example, PT1M (one minute data), PT2M (2 minutes data), and so on till PT15M (15 minutes data).

  • dimension_key: Unique identifer of a dimension to group the metric data.

Analyze real time metrics data (active_devices,active_users,page_views,total_events), group by countries (geo_country).

Example Request

Copy 
https://api.conviva.com/analytics/real-time-metrics/active_devices,active_users,page_views,total_events/PT1M/group-by/geo_country

Example Response

Copy 
{
  "time_series": [
    {
      "dimensional_data": [
        {
          "dimension": {
            "key": "geo_country",
            "value": "Spain",
            "country_code": "ES"
          },
          "metric_data": {
            "active_devices": 35053,
            "active_users": 20197,
            "page_views": 1988,
            "total_events": 139161
          }
        },
        {
          "dimension": {
            "key": "geo_country",
            "value": "France",
            "country_code": "FR"
          },
          "metric_data": {
            "active_devices": 421,
            "active_users": 186,
            "page_views": 48,
            "total_events": 2136
          }
        }
        // more timeseries data for different countries
      ]
    }
  ],
  "aggregated_metric_data": {
    "active_devices": 38637,
    "active_users": 21987,
    "page_views": 2212,
    "total_events": 151997
  }
}

 

Historical Metric Data Group-By a Dimension

This section explains how to use a dimension to group historical metric data.

URL

Copy 
https://api.conviva.com/analytics/metrics/{selected_metric_keys}/{start_timestamp}_to_{end_timestamp}/group-by/{group_by_dimension}

Execute the API with required parameters in URI path:

  • selected_metric_keys: Specify at most 12 metric keys as a comma-separated list in the path parameter. For example, active_devices,active_users,page_views,total_events and so on.

  • start_timestamp: The start time of a time interval in epoch ms or ISO 8601 format.

  • end_timestamp: The end time of a time interval in epoch ms or ISO 8601 format.

  • dimension_key: Unique identifer of a dimension to group the metric data.

Note: The start_timestamp should be earlier than the end_timestamp.

 

Analyze the historical metrics data (active_devices,active_users,page_views,total_events) group by countries (geo_country).

Example Request

Copy 
https://api.conviva.com/analytics/metrics/active_devices,active_users,page_views,total_events/1751994600000_to_1751996400000/group-by/geo_country

Example Response

Copy 
{
  "time_series": [
    {
      "dimensional_data": [
        {
          "dimension": {
            "key": "geo_country",
            "value": "Spain",
            "country_code": "ES"
          },
          "metric_data": {
            "active_devices": 194543,
            "active_users": 93860,
            "page_views": 132056,
            "total_events": 5428007
          }
        },
        {
          "dimension": {
            "key": "geo_country",
            "value": "Mexico",
            "country_code": "MX"
          },
          "metric_data": {
            "active_devices": 2925,
            "active_users": 1328,
            "page_views": 1980,
            "total_events": 134184
          }
        }
        // metric data set for more countries
      ]
    }
  ],
  "aggregated_metric_data": {
    "active_devices": 212628,
    "active_users": 101523,
    "page_views": 146643,
    "total_events": 6132904
  }
}

 

Apply Advanced Filtering

In addition to grouping by dimensions, the Analytics API also allows filtering data by one or more dimensions using the filter query parameter. Filters help narrow down the dataset to match the specific criteria, such as focusing on a particular device type, location, or any other available dimension.

To apply a filter, append the ?filter= query parameter to the API request URL, and construct the filter condition using a syntax similar to SQL WHERE clause.

Request Format

Copy 
/?filter={dimension_key} == 'matching value of the dimension'

Example of Filtering Real-Time Metric Data

Analyze real-time metrics over the past 5 minutes (PT5M), grouped by country, and filter metrics data only for United States (filter=(geo_country == 'United States')).

Copy 
https://api.conviva.com/analytics/real-time-metrics/active_devices,active_users,page_views,total_events/PT5M/group-by/geo_country/?filter=(geo_country == 'United States')

Example of Filtering Historical Metric Data

Analyze historical metrics between a given time, grouped by country, and filter the metrics data only for United States (filter=(geo_country == 'United States')).

Copy 
https://api.conviva.com/analytics/metrics/active_devices,active_users,page_views,total_events/1421751994600000_to_1751996400000/group-by/geo_country/?filter=(geo_country == 'United States')

List of Supported Operators

Conviva Analytics API supports the following operators to use with the filter criteria in the query string:

  • == (equals)

  • != (not equals)

  • ~~ (contains substring)

  • !~ (does not contain)

  • AND (logical And)

  • OR (logical Or)

  • ( ) (grouping for precedence)

Example of Using Multiple Filters

Use the AND operator to combine multiple filtering criteria by using the correct dimension_key.

For Example:

Copy 
/?filter=(device_operating_system == 'Android' AND geo_country == 'Spain')

HTTPS Response Codes

Successful execution of Analytics API request is represented by the response code 200.

Client-side error codes start with the number 4 (4xx):

Response Code Value Description
400 Bad Request Request with syntactical errors (incorrect structure).
404 Not Found Request path does not exists.
414 Request-URI Too Long Request URL length exceeds the limit of 4K characters.
422 Unprocessable Entity Request is syntactically correct but with incorrect value, for example, the end time is before the start time.
429 Too Many Requests Request is rate limited.

 

Analytics API Analytics API Analytics API Analytics API Analytics API Guide Analytics API Guide Analytics API Guide DPI Analytics API DPI Analytics API DPI Analytics API DPI Analytics API