Conviva APIs

Conviva's Sessions V3 API provides programmatic access to session data. Each Conviva session represents a viewing stream of a video or ad content where session aggregations are used to calculate metrics on Pulse.

Use the Sessions V3 API to retrieve viewer experience details from the video content based on viewer ID or viewer's IP address.

For a quick glance at the examples of how the APIs work, refer to the Getting Started page.

API Access Rate Limit

To know the API access limits, refer to the details on Conviva API Developer Center. For more information about rate plans, contact Conviva representative.

API Access

To access the API, contact the account representative to get the API authentication information, including CLIENT_ID and CLIENT_SECRET. For more details, refer to API Authentication.

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

Key Features of Sessions V3

Retrieve filterable sample sessions by combining statuses, metrics, and dimensional metadata.
Retrieve a particular viewer's session data using the viewer ID or viewer IP address value.

Types of Sessions

Sessions V3 API supports fetching three types of sessions:

Session Type	Endpoint	Description
Content Sessions	GET https://api.conviva.com/insights/3.0/sessions/content	Samples of Video Content Sessions
Ad Sessions	GET https://api.conviva.com/insights/3.0/sessions/ad	Samples of Ad Sessions
Viewer Sessions	GET https://api.conviva.com/insights/3.0/sessions/content/viewer	A Viewer's Video Content Sessions (Viewer Experience)

Ad sessions are available only for accounts that have Ad Insights enabled. Viewer sessions are available only for accounts that have Viewer-Module API enabled.

To know the endpoints that are available, see the Discovery Endpoint API.

Time Range

To retrieve sessions, every API request needs a time range.

GET https://api.conviva.com/insights/3.0/sessions/content?start_date=2022-01-01T04:00:00Z&end_date=2022-01-02T04:00:00Z
GET https://api.conviva.com/insights/3.0/sessions/ad?start_epoch=1641009600&end_epoch=1641096000
GET https://api.conviva.com/insights/3.0/sessions/content/viewer?days=30

Provide a specific time range in the querystring and use one of the predefined time range formats to specify a time range.

Note: Use only one time-range format per request.

Example

The following request retrieves sample content sessions of the time range January 01 2023 1 AM - January 02 2023 4 AM(from 2023-01-01T01:00:00Z to 2023-01-02T04:00:00Z) using ISO 8601 date-time format:

Copy

GET https://api.conviva.com/insights/3.0/sessions/content?start_date=2023-01-01T01:00:00Z&end_date=2023-01-02T04:00:00Z

Retrieving Sample Sessions

The Sample Sessions endpoints return only the ended sessions, which means they do not return the on-going sessions.

Example of Retrieving Sample Sessions (Using Default Behavior)

To retrieve sample session data:

Copy

GET https://api.conviva.com/insights/3.0/sessions/{data_source}

where {data_source} can be either content or ad. By default, if there are no query parameters, the endpoints use the following behavior:

Filtering with “All Traffic“ (no filters).
Time interval of the latest 3 hours (using the request time as a reference).
Limited to return 50 sample sessions.

Specifying the Limit

Use the ?limit={N} query parameter to specify the number of sample sessions in the response (1 ≤ N ≤ 500). Set a limit to control the number of sessions in the response. As example, to limit the response upto 10 sessions:

Copy

GET https://api.conviva.com/insights/3.0/sessions/content?limit=10

Retrieving IP and IPv6 information

In the response, the network_info section shows ip and ipv6 along with asn, cdn, isp, last_cdn_edge_server, and last_cdn_group_id.

Copy

"network_info": {
      "asn": {
        "value": "33491",
        "description": "COMCAST-33491 - Comcast Cable Communications, LLC, US"
      },
      "cdn": [
        "INHOUSE"
      ],
      "ip": "173.46.225.209",
      "ipv6": null,
      "isp": "Comcast",
      "last_cdn_edge_server": "",
      "last_cdn_group_id": ""
    }

Filtering by Dimensions

The Sample Sessions endpoints support filtering by various dimensions (predefined by Conviva, as well as custom tags). Refer to the Dimensions page to find the list of supported filtering dimensions defined by Conviva.

Dimensions are configured during the sign-up and integration with Conviva. Not all predefined dimensions may be available for the account. Use the list dimensions endpoint to look up the list of available filtering dimensions for the account.

To add more dimensions to the account, contact account manager or Conviva Support (support@conviva.com).

Using query parameters to specify dimensional filters:

Example

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

Copy

GET https://api.conviva.com/insights/3.0/sessions/content?geo_city_name=Los Angeles, California, United States&device_os=Android

Besides predefined dimensions, it's also possible to filter using custom tags. Prefix tag_ to the tag name and use that as the query parameter key.

Example

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

Copy

GET https://api.conviva.com/insights/3.0/sessions/content?tag_specialContentId=1A2B3C4D5E

Note: Dimension values are case-sensitive.

Use multiple dimensions in a request:

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.

Sessions V3 API shares the same filtering logic with Metrics V3 API. Reuse the same filter query string for both APIs.

Filtering by a Saved Filter

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

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

Each saved filter has a filter id that serves as a unique identifier. Apply the saved filter using the filter_id query parameter, and specify the id as the query value in the API request.

Note: The filter_id query parameter is singular and expects only one id value.

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

Example

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

Copy

GET https://api.conviva.com/insights/3.0/sessions/content?filter_id=9876543210

Use Case: Diagnosing Video Content Errors

To illustrate the utility of the sample sessions endpoints, let's assume there is a hypothetical instance of increased Video Start Failure Technical errors for devices running Android 9 and Android 10, and streaming via the Native App.

Use the following request to retrieve a sample of sessions for investigation:

Copy

GET https://api.conviva.com/insights/3.0/sessions/content?is_video_start_failure_tech=true&device_os_version=Android 9&device_os_version=Android 10&browser_name=Native App

where

is_video_start_failure_tech=true filters sessions with Video Start Failure Technical error.
device_os_version=Android 9&device_os_version=Android 10 filters sessions with devices running either Android 9 or 10.
browser_name=Native App filters sessions stream via Native App.

The response sessions also include error codes that help determine the cause of the errors.

Viewer's Streaming Sessions and Summary Metrics

Sessions V3 API retrieves a list of viewer sessions and the summary metrics.

Retrieving Viewer's Streaming Sessions

The API returns both ended and on-going viewer sessions.

Note: Conviva supports viewer sessions from the video content data source only.

Example of Retrieving Viewer's Sessions

To retrieve a viewer's session data by identifier:

Copy

GET https://api.conviva.com/insights/3.0/sessions/content/viewer?viewer_id={viewer_id_value}

OR by their IP address:

Copy

GET https://api.conviva.com/insights/3.0/sessions/content/viewer?viewer_ip={viewer_ip_address_value}

where {viewer_ip_address_value} can be in either IPv4 or IPv6 format.

Number of Sessions in Response

This endpoint returns maximum 500 viewer sessions.

Set a limit to control the number of viewers sessions in the response. As example, to limit the response upto 10 sessions:

Content sessions endpoint

Copy

GET https://api.conviva.com/insights/3.0/sessions/content/viewer?limit=10

Ad sessions endpoint

Copy

GET https://api.conviva.com/insights/3.0/sessions/ad/viewer?limit=10

Note: To get more than 500 viewer sessions, split the query time range into multiple intervals.

Retrieving Viewer's Sessions Summary Metrics

Determine a viewer's overall stream experience using the number of plays, total minutes watched, session SPI, startup/play failures, rebuffering and average peak bitrates, and can also check specific performance measurements of each session.

Retrieve by identifier:

Copy

GET https://api.conviva.com/insights/3.0/sessions/content/viewer/summary?viewer_id={viewer_id_value}

Retrieve by IP address:

Copy

GET https://api.conviva.com/insights/3.0/sessions/content/viewer/summary?viewer_ip={viewer_ip_address_value}

where {viewer_ip_address_value} can be in either IPv4 or IPv6 format.

The request takes in either a viewer_ip or viewer_id, and not both. The response contains only the total metrics, and doesn't include the time_series interval.

Sample Request

Copy

GET https://api.conviva.com/insights/3.0/sessions/content/viewer/summary?viewer_id=47a28f72-6ad8-4a3b-813e-bd04eecda689&days=1

Sample Response

Copy

{
    "total": {
        "bitrate": {
            "bps": 0
        },
        "connection_induced_rebuffering_ratio": {
            "ratio": 0
        },
        "ended_plays_duration": {
            "mins": 0,
            "per_ended_play": 0,
            "per_unique_device": 0
        },
        "exit_before_video_starts": {
            "count": 0,
            "percentage": 0
        },
        "good_streams": {
            "count": 0
        },
        "good_streams_average_play_time": {
            "mins": 0
        },
        "impacted_streams": {
            "count": 0
        },
        "impacted_streams_average_play_time": {
            "mins": 0
        },
        "plays": {
            "count": 0
        },
        "rebuffering_ratio": {
            "ratio": 0
        },
        "spi_streams": {
            "count": 0
        },
        "streaming_performance_index": {
            "value": 0
        },
        "unique_devices": {
            "count": 0
        },
        "video_playback_failures": {
            "count": 0,
            "percentage": 0
        },
        "video_playback_failures_business": {
            "count": 0,
            "percentage": 0
        },
        "video_playback_failures_tech": {
            "count": 0,
            "percentage": 0
        },
        "video_restart_time": {
            "value": 0
        },
        "video_start_failures": {
            "count": 0,
            "percentage": 0
        },
        "video_start_failures_business": {
            "count": 0,
            "percentage": 0
        },
        "video_start_failures_tech": {
            "count": 0,
            "percentage": 0
        },
        "video_start_time": {
            "value": 0
        }
    },
    "_meta": {
        "queries": {
            "viewer_id": "47a28f72-6ad8-4a3b-813e-bd04eecda689",
            "start_epoch_ms": 1690136399898,
            "end_epoch_ms": 1690222799898
        },
        "query_string": "viewer_id=47a28f72-6ad8-4a3b-813e-bd04eecda689&start_epoch_ms=1690136399898&end_epoch_ms=1690222799898",
        "ratio_info": {
            "connection_induced_rebuffering_ratio": {
                "max": 100
            },
            "rebuffering_ratio": {
                "max": 100
            }
        },
        "annotations": [
            {
                "cause": "Integrity service adjusted query interval",
                "value": "5 minutes"
            }
        ]
    }
}

Use Case: Viewer Experience Dashboard for Customer Care

The viewer sessions and summary endpoints provide details of viewer streaming experience across the sessions watched in a given time period. Build dashboards for the customer care teams powered by this data. The request requires a valid viewer IP address (for example, 11.22.33.44) or a valid viewer identifier, and a query time range (for example, the last 20 days).

If no time range is specified, the API by default queries an interval of the last one day.

Copy

GET https://api.conviva.com/insights/3.0/sessions/content/viewer?viewer_ip=11.22.33.44&days=20

For more details, see the Viewer Module Dashboards.

Response Format

The Sessions V3 API response contains an array of session objects. Each session object contains the following categories of attributes.

Key	Description
conviva_session_id	concatenation of client_id and session_id (see SSD fields).
viewer_id	Only available to accounts with viewer-module access.
timestamps	start and end timestamps
status_info	Session statuses and errors.
lifetime_metrics	Numerical metric values calculated based on the entire lifetime of the session.
content_info	Content related information.
device_info	Playing device information.
geo_info	Viewer location information.
network_info	Network connection information.
tags.selected_dimensions	Preselected Conviva-defined dimensions.
tags.custom_tags	Custom tags dimensions of the account.

Sample Response:

Copy

{
  "sessions": [
    {
      "conviva_session_id": "1.2.3.4.-5",
      "client_id": "1.2.3.4",
      "session_id": "-5",
      "viewer_id": "### REDACTED ###",
      "timestamps": {
        "start": {
          "epoch_ms": 1678829756486,
          "iso_date": "2023-03-14T21:35:56.486Z"
        },
        "end": {
          "epoch_ms": 1678829756487,
          "iso_date": "2023-03-14T21:35:56.487Z"
        }
      },
      "status_info": {
        "is_ended": true,
        "ended_status": "By Expiration",
        "is_exit_before_video_start": true,
        "is_video_start_failure": false,
        "is_video_start_failure_business": false,
        "is_video_start_failure_tech": false,
        "is_video_playback_failure": false,
        "is_video_playback_failure_business": false,
        "is_video_playback_failure_tech": false,
        "errors": []
      },
      "lifetime_metrics": {
        "average_framerate_fps": 0,
        "average_peak_bitrate_bps": 0,
        "average_percentage_complete": 0,
        "bitrate_switches_count": 0,
        "connection_induced_rebuffering_ratio_percent": 0,
        "connection_induced_rebuffering_time_ms": 0,
        "last_play_head_time_ms": -1,
        "playing_time_ms": 0,
        "paused_ratio_percent": 0,
        "paused_time_ms": 0,
        "rebuffering_ratio_percent": 0,
        "rebuffering_time_ms": 0,
        "video_restart_time_ms": 0,
        "video_start_time_ms": -3000
      },
      "content_info": {
        "asset": "Detective Memoirs: S1, E1",
        "category": "VoD",
        "length_ms": 900000,
        "stream_url": "example.com"
      },
      "device_info": {
        "browser": {
          "name": "Native App",
          "version": "Native App"
        },
        "name": "Apple iPhone",
        "os": "iOS",
        "os_family": "iOS",
        "os_version": "iOS Unknown"
      },
      "geo_info": {
        "city": "Chicago, Illinois, United States",
        "state": {
          "name": "Illinois, United States",
          "code": "IL"
        },
        "country": {
          "name": "United States",
          "code": "US"
        },
        "continent": "North America",
        "postal_code": "60609",
        "dma": "Chicago"
      },
      "network_info": {
        "asn": {
          "value": "33491",
          "description": "COMCAST-33491 - Comcast Cable Communications, LLC, US"
        },
        "cdn": [
          "INHOUSE"
        ],
        "ip": "173.46.225.209",
        "ipv6": null,
        "isp": "Comcast",
        "last_cdn_edge_server": "",
        "last_cdn_group_id": ""
      },
      "tags": {
        "selected_dimensions": {
          "ad_creative_id": "",
          "ad_id": "",
          "ad_media_file_api_framework": "",
          "ad_planned_duration": "",
          "ad_position": "",
          "ad_sequence": "",
          "ad_system": "",
          "ad_technology": "",
          "app_version": "AV_5.45",
          "browser_name": "Native App",
          "browser_version": "Native App",
          "content_category": "VoD",
          "content_meta_channel": "The Premium Channel",
          "content_meta_show_title": "Detective Memoirs: S1, E1",
          "content_session_id": "",
          "device_hardware_type": "Mobile Phone",
          "device_manufacturer": "Apple",
          "device_marketing_name": "Apple iPhone 4S",
          "device_model": "iPhone 4S",
          "device_name": "Apple iPhone",
          "device_os": "iOS",
          "device_os_family": "iOS",
          "device_os_version": "iOS Unknown",
          "platform_version": "",
          "player_framework_name": "",
          "player_framework_version": "",
          "player_name": "iOS AVPlayer",
          "video_asset_name": ""
        },
        "custom_tags": {
          "absoluteIndex": "",
          "ad_break_duration": "90",
          "age": "65",
          "demo_version": "2022.10.13+rollback_eff17a6",
          "has_ad": "true",
          "has_preroll": "",
          "linked_ad": "pre-mid-roll",
          "podIndex": "",
          "podPlannedDuration": "",
          "podRollPostion": ""
        }
      }
    }
  ]
}

Conviva Sessions V3 API Conviva Sessions V3 API Conviva Sessions V3 API