DPI Flow API - Quick Start Guide

 

The DPI Flow API provides real-time Flow statistics, suitable for integration into internal dashboards and analytics systems. This page outlines how the API works, enabling fast and efficient implementation.

Note: The DPI Flow 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.

About Flows

DPI Flows represent critical steps in real-user journeys that enable continuous monitoring and step-wise activity progress in real-time, measuring critical user journey durations, success rates, and completions. Define custom Flows aligned with business outcomes, such as conversions or error-influenced checkouts, and use the out-of-the-box dashboards to monitor KPIs like success rate, inits, duration, and errors.

For more information, see DPI Flows.

Common Use Cases

DPI Flow API enables a range of high-impact use cases across operational monitoring, product analytics, and automated workflows. Some key scenarios where the API delivers value:

  • Real-Time App Health Dashboards: Product and Engineering teams can utilize the API to empower their dashboards that surface real-time metrics on application health, audience engagement, and user journey performance. Common use cases include tracking number of audiences and successful checkouts.

  • Historical Performance Dashboards: Product, Strategy, and Engineering stakeholders can leverage the API to populate dashboards with historical metrics, enabling long-term trend analysis and comparative performance reviews. A typical use case involves evaluating time-to-value metrics across different product releases.

  • Trigger Automated Business Processes: Engineering teams can use the Flow data to programmatically initiate downstream workflows based on dynamic thresholds, such as conversion rates, Flow volumes, or reliability levels. For instance, infrastructure provisioning can be triggered when hourly login Flow volumes exceed predefined limits.

  • Operations Monitoring: Operations teams can integrate the Flow metrics with existing monitoring tools to enhance visibility into real-time application performance, user activity, and infrastructure reliability. This includes tracking key indicators such as API response times and Flow error rates.

DPI Flow API Sequence

Retrieve the Flow data in the following sequence:

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

Get Method

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

Note: The DPI Flow API accepts only the https GET method. Server rejects any API requests made using http with an error.

API Security

HTTPS encrypts data while transmitting between clients and servers. It protects the data from unauthorized access and ensures overall system security.

Header Authentication

To access any Conviva APIs, it is required to provide an API key (client-Id and client-secret). Generate the credentials from the Pulse API Management page.

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

Note: Pulse user-based credentials and Conviva API keys are different. Calling any Conviva APIs with Pulse user-based credentials results in unrecognized credentials and authentication failure.

Content Type: application/JSON

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

Get Flow Metrics and Dimensions

Retrieve the list of Flows, with associated metrics and dimensions available for the user's account.

Request

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

Response

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

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

Copy 
{
  "flow_models": [
    {
      "id": "825",
      "label": "Login Process",
      "metrics": [
        {
          "key": "m_825_1",
          "label": "Login Process Complete",
          "unit": "count",
          "type": "complete",
          "percentage_metric": {
            "key": "m_825_1_percentage"
          }
        },
        
        // more Flow metrics
      ],
      "dimensions": [
        {
          "key": "geo_country",
          "label": "Countries"
        },
        
        // more Flow dimensions
      ]
    }
  ]
}

 

Get Metric Data in Time Series Format

Retrieve the metrics data of a Flow in a given time series format:

Analyze Real-Time Time Series Metric Data

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

URL

Copy 
https://api.conviva.com/flow-data/real-time-metrics/{flow_entity_id}/{relative_time_interval}

Execute the API with required parameters in URI path:

  • flow_entity_id: The identifier of a Flow Model. Every Flow is assigned to a unique id.

  • 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 last 5 minutes metrics data of the 'Login Process' Flow (id is 825) with 1 minute interval. Specify the 1-minute interval as a filter criteria in the query srting. It slice the last 5 minutes metric data into 1-minute interval, and ensures granularity into the response data for better analysis.

Example Request

Copy 
https://api.conviva.com/flow-data/real-time-metrics/825/PT5M?granularity=PT1M

Example Response

Copy 
{
  "time_series": [
    {
      "timestamp": {
        "epoch_ms": 1754421950000,
        "iso_date": "2025-08-05T19:25:50.000Z"
      },
      "metric_data": {
        "m_825_1": 1,
        "m_825_1_percentage": 100,
        "m_825_2": 0.663,
        "m_825_3": 1,
        "m_825_4": 1,
        "m_825_4_percentage": 100
      }
    },
    {
      "timestamp": {
        "epoch_ms": 1754422010000,
        "iso_date": "2025-08-05T19:26:50.000Z"
      },
      "metric_data": {
        "m_825_1": 3,
        "m_825_1_percentage": 100,
        "m_825_2": 0.4716666666666667,
        "m_825_3": 3,
        "m_825_4": 3,
        "m_825_4_percentage": 100
      }
    },
    // 3 more data points
  ],
  "aggregated_metric_data": {
    "m_825_1": 13,
    "m_825_1_percentage": 100,
    "m_825_2": 0.6031538461538462,
    "m_825_3": 13,
    "m_825_4": 13,
    "m_825_4_percentage": 100
  }
}

 

Analyze Historical Time Series Metric Data

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

URL

Copy 
https://api.conviva.com/flow-data/metrics/{flow_entity_id}/{start_timestamp}_to_{end_timestamp}}

Execute the API with required parameters in URI path:

  • flow_entity_id: The identifier of a Flow Model. Every Flow is assigned to a unique id.

  • 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 of a Flow (id is 142).

Example Request

Copy 
https://api.conviva.com/flow-data/real-time-metrics/142/1751994600000_to_1751996400000

Example Response

Copy 
{
  "time_series": [
    {
      "timestamp": {
        "epoch_ms": 1751994600000,
        "iso_date": "2025-07-08T17:10:00.000Z"
      },
      "metric_data": {
        "m_142_1": 9505,
        "m_142_1_percentage": 71.00171808470904,
        "m_142_2": 50.117175170962646,
        "m_142_3": 13387,
        "m_142_4": 8266,
        "m_142_4_percentage": 61.746470456412936
      }
    },
    {
      "timestamp": {
        "epoch_ms": 1751996400000,
        "iso_date": "2025-07-08T17:40:00.000Z"
      },
      "metric_data": {
        "m_142_1": 8997,
        "m_142_1_percentage": 71.17316667985128,
        "m_142_2": 51.55650794709347,
        "m_142_3": 12641,
        "m_142_4": 7767,
        "m_142_4_percentage": 61.442923819318096
      }
    }
  ],
  "aggregated_metric_data": {
    "m_142_1": 18502,
    "m_142_1_percentage": 71.0849854003381,
    "m_142_2": 50.8170820451843,
    "m_142_3": 26028,
    "m_142_4": 16033,
    "m_142_4_percentage": 61.599047179960046
  }
}

 

Get Metric Data By Dimensions

For a given Flow, retrieve the metric data grouped by dimension. Dimensions allow you to categorize metric data into smaller, more manageable groups. This helps achieve deeper insights into the granular segment of metric data. For example, analyze the Login Process Flow metrics group by different dimensions, such as device category, operating system, country, or zip code.

See the list of dimenstions available for analyzing the metrics of the Flows. Each dimension is asigned to a key. While executing an API call, specify the dimension key in the URI path.

Let's see:

Real-time Group-By Dimension Metric Data

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

URL

Copy 
https://api.conviva.com/flow-data/real-time-metrics/{flow_entity_id}/{relative_time_interval}/group-by/{dimension_key}

Execute the API with required parameters in URI path:

  • flow_entity_id: The identifier of a Flow Model. Every Flow is assigned to a unique id.

  • 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 of a Flow (id is 142), group by countries.

Example Request

Copy 
https://api.conviva.com/flow-data/real-time-metrics/142/PT1M/group-by/geo_country

Example Response

Copy 
{
  "time_series": [
    {
      "dimensional_data": [
        {
          "dimension": {
            "key": "geo_country",
            "value": "Spain",
            "country_code": "ES"
          },
          "metric_data": {
            "m_142_1": 454,
            "m_142_1_percentage": 75.41528239202658,
            "m_142_2": 58.6976563876652,
            "m_142_3": 602,
            "m_142_4": 397,
            "m_142_4_percentage": 65.9468438538206
          }
        },
        {
          "dimension": {
            "key": "geo_country",
            "value": "United Kingdom",
            "country_code": "GB"
          },
          "metric_data": {
            "m_142_1": 11,
            "m_142_1_percentage": 78.57142857142857,
            "m_142_2": 5.539272727272727,
            "m_142_3": 14,
            "m_142_4": 11,
            "m_142_4_percentage": 78.57142857142857
          }
        }
      ]
    }
  ],
  "aggregated_metric_data": {
    "m_142_1": 499,
    "m_142_1_percentage": 74.81259370314842,
    "m_142_2": 56.01587975951904,
    "m_142_3": 667,
    "m_142_4": 440,
    "m_142_4_percentage": 65.96701649175412
  }
}

 

Historical Group-By DimensionMetric Data

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

URL

Copy 
https://api.conviva.com/flow-data/metrics/{flow_entity_id}/{start_timestamp}_to_{end_timestamp}}/group-by/{dimension_key}

Execute the API with required parameters in URI path:

  • flow_entity_id: The identifier of a Flow Model. Every Flow is assigned to a unique id.

  • 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: Remember, the start_timestamp should be earlier than the end_timestamp.

 

Analyze the historical metrics data of a Flow (id is 142) group by countries.

Example Request

Copy 
https://api.conviva.com/flow-data/metrics/142/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": {
            "m_142_1": 18279,
            "m_142_1_percentage": 73.7502521686504,
            "m_142_2": 55.47876940751683,
            "m_142_3": 24785,
            "m_142_4": 15762,
            "m_142_4_percentage": 63.59491628000807
          }
        },
        {
          "dimension": {
            "key": "geo_country",
            "value": "Germany",
            "country_code": "DE"
          },
          "metric_data": {
            "m_142_1": 273,
            "m_142_1_percentage": 76.04456824512535,
            "m_142_2": 26.383490842490843,
            "m_142_3": 359,
            "m_142_4": 245,
            "m_142_4_percentage": 68.24512534818942
          }
        }
      ]
    }
  ],
  "aggregated_metric_data": {
    "m_142_1": 20600,
    "m_142_1_percentage": 72.32130318775452,
    "m_142_2": 54.67840004854369,
    "m_142_3": 28484,
    "m_142_4": 17761,
    "m_142_4_percentage": 62.35430417076253
  }
}

 

Apply Advanced Filtering

In addition to grouping by dimensions, the Flow 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={filter_dimension_key} == 'matching value of the filter_dimension'

Example of Filtering Real-Time Metric Data

Analyze real-time metrics for the specified Flow ID (825) over the past 5 minutes (PT5M), grouped by country, and filter metrics data only from the devices running on Android operating system (device_operating_system == 'Android').

Copy 
https://api.conviva.com/flow-data/real-time-metrics/825/PT5M/group-by/geo_country/?filter=device_operating_system == 'Android'

Example of Filtering Historical Metric Data

Analyze historical metrics for the specified Flow ID (142) between a given time, grouped by country, and filter the metrics data from any devices running on any operating systems other than Android (device_operating_system != 'Android').

Copy 
https://api.conviva.com/flow-data/metrics/1421751994600000_to_1751996400000/group-by/geo_country/?filter=device_operating_system != 'Android'

List of Supported Operators

Conviva Flow 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 Flow 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, may be due to invalid Flow id.
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.

 

Flow API Flow API Flow API Flow API Flow API Guide Flow API Guide Flow API Guide DPI Flow API DPI Flow API DPI Flow API DPI Flow API