Conviva Sessions V3 API: Getting Started

 

Learn about the Sessions V3 APIs and how to use them.

We've provided examples to retrive session data.

  • Step 1: Identify which endpoint to query.

  • Step 2, 3, and 4: Construct a query request.

  • Step 5: Interpret session data in the response format.

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.

1. Select a Session Endpoint

Use the discovery endpoint to see which of the following paths are available for the account.

Path Description Prerequisites Predecessor
GET https://api.conviva.com/insights/3.0/sessions/content Samples of Video Content Sessions   Session API V1 /platform/v1/*
GET https://api.conviva.com/insights/3.0/sessions/ad Samples of Ad Sessions Ad Insights  
GET https://api.conviva.com/insights/3.0/sessions/content/viewer Viewer Experience Details Viewer-Module API Viewer-Module /viewer/views.json

 

(Optional) Each request requires a time range of start and end timestamps.

For examples:

  • 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

2. Request a Publisher's Sample Sessions Filter By Dimensions

Only the Sample Sessions endpoints (/sessions/content or /sessions/ad) can be filtered by dimensions.

Example:

Requests with Dimension Filters

To retrieve video content sessions from Android devices and the Verizon ISP, specify the request to filter by device_os and isp dimensions by appending them as query string parameters.

Copy 
GET https://api.conviva.com/insights/3.0/sessions/content?device_os=Android&isp=Verizon

To retrieve sessions with Video Start Failures (useful for debugging), use ?is_video_start_failure=true dimension:

Copy 
GET https://api.conviva.com/insights/3.0/sessions/content?device_os=Android&isp=Verizon&is_video_start_failure=true

Refer to Filtering by Dimensions page to find a complete list of supported dimensions. Also, retrieve the list reference dimensions to look up the list of available filtering dimensions for the account.

3. Request a Viewer's Sessions

The Viewer Experience sessions endpoint requires either a ?viewer_id or a ?viewer_ip (can be in IPv4 or IPv6 format) query parameter for filtering.

Example:

Request Sessions of a Viewer

Copy 
GET https://api.conviva.com/insights/3.0/sessions/content/viewer?viewer_id=1a2b3c4d5e

This endpoint returns a maximum of 500 viewer sessions. To get more than 500 viewer sessions, split the query time range into multiple intervals.

Normal accounts have access to the most recent 30 days of viewer data; contact the account manager to access up to 90 days of viewer data.

4. Specify A Time Range

To query for a specific time range, use the start and end time in the querystring.

There are multiple ways to specify a time range.

  • by date, epoch or epoch_ms values (in conjunction with start_/end_ prefixes), for example:

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

    • GET https://api.conviva.com/insights/3.0/sessions/ad?start_epoch=1672545600&end_epoch=1672549200

  • by the last number of days (only available for GET /3.0/sessions/content/viewer endpoint), for example:

    • GET https://api.conviva.com/insights/3.0/sessions/content/viewer?viewer_id=1ab2c34d5e&days=30

 

5. Interpret Session Response

The response returns 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.

 

Sessions V3 API Getting Started Sessions V3 API Getting Started Sessions V3 API Getting Started