Conviva Sessions V3 API: Getting Started

Learn about the Sessions V3 APIs and how to use them. Identify which endpoint to query, construct a query request, and interpret session data in the response format, with examples for retrieving session data.

Updated 2026-09-09 sessions-api-getting-started

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 in an interactive query, split the query time range into multiple intervals.

Best practice: For bulk per-viewer or per-session history, use Connect Data Feeds (Session Feed) rather than looping one viewer_id per call. Per-viewer loops exhaust the shared analytical rate limit. See Efficient API Usage: Bulk per-viewer data.

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.