Validation Timeline API (v1) Validation Timeline API retrieves the session associated with a Viewer ID, Session ID or combination of both. It provides our customers with real-time self-validation capabilities for Conviva's SDK integrated into their application.

Validation Timeline API (v1)

Validation Timeline API retrieves the session associated with a Viewer ID, Session ID or combination of both. It provides our customers with real-time self-validation capabilities for Conviva's SDK integrated into their application. This API enables our customers to automate the validation of Conviva SDKs.

The Validation Timeline API offers a straightforward, efficient, and secure approach to gathering session summaries, event timelines, and metadata, thereby facilitating real-time anomaly detection.

URLs

Copy

https://api.conviva.com/validation/v1/timeline?viewer_id={value}&session_id={value}

https://api.conviva.com/validation/v1/timeline?session_id={value}

https://api.conviva.com/validation/v1/timeline?viewer_id={value}

Method: GET

This method acts like a digital query to collect the session summary, event timelines, and metadata in JSON format.

Case	Request	Response
1	Query with the combination of a valid viewer_id and session_id. URL: https://api.conviva.com/validation/v1/timeline?viewer_id={value}&session_id={value}	Retrieves the session summaries, event timelines, and metadata of a particular viewer’s session.
2	Query with only a valid session_id. URL: https://api.conviva.com/validation/v1/timeline?session_id={value}	Retrieves the session summaries, event timelines, and metadata of a particular viewer’s session.
3	Query with only a valid viewer_id. URL: https://api.conviva.com/validation/v1/timeline?viewer_id={value}	Retrieves the session summaries, event timelines, and metadata of the latest viewer’s session.

Case

Request

Response

Query with the combination of a valid viewer_id and session_id.

URL:

https://api.conviva.com/validation/v1/timeline?viewer_id={value}&session_id={value}

Retrieves the session summaries, event timelines, and metadata of a particular viewer’s session.

Query with only a valid session_id.

URL:

https://api.conviva.com/validation/v1/timeline?session_id={value}

Retrieves the session summaries, event timelines, and metadata of a particular viewer’s session.

Query with only a valid viewer_id.

URL:

https://api.conviva.com/validation/v1/timeline?viewer_id={value}

Retrieves the session summaries, event timelines, and metadata of the latest viewer’s session.

Security: HTTPS

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

Authentication

To access the API use the client-based credentials, client-Id and client-secret, generated in Pulse from the API Management page, accessed from the Pulse Settings menu. For more details, see Pulse API Management page.

Content-Type

application/JSON

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

Response

Summary

Field	Datatype	Description
asset	string	The first known asset played by this video session.
app_name	string	Name of the application a session is played.
device_name	string	Name of the device a session is played.
device_hardware_type	string	The physical form-factor type of the device where a session is played.
device_os	string	The name of the OS running on the device that played this video session.
device_os_family	string	The Operating System family where a particular session is played.
browser_name	string	Name of the browser where a particular session is played.
browser_version	string	Version of the browser where a particular session is played.
session_start_timestamp_ms	long	The epoch timestamp in milliseconds when the session is started or revived.
session_end_timestamp_ms	long	The epoch timestamp in milliseconds when the session is ended. The value is null if Conviva hasn't seen the end of the session when the query is processed.
video_start_time_ms	Union of long, string, and NUL	The possible values are: Time in milliseconds (long), that a player takes to start playing a video. Not Joined (string): If a video did not play. Joined but Unknown (string): If a video played but Conviva is unable to detect the startup time of that video. NULL: If Conviva is unable to determine whether a video played and its startup time.
play_status	string	The latest status of the specific video session: EBVS (Exit Before Video Start) VSF (Video Start Failure) Ongoing but not Joined Joined and Ongoing VPF (Video Playback Failure) Ended
playing_time_ms	long	Total playing time in the specific video session. The value is displayed in terms of milliseconds.
rebuffering_time_ms	long	Total rebuffering time in the specific video session. The value is displayed in terms of milliseconds.
connection_induced_rebuffering_time_ms	string	Total rebuffering time for the specific video session, excluding time from rebuffering events triggered by seek. The value is displayed in terms of milliseconds.
average_peak_bitrate_bps	long	The lifetime average bitrate for the specific video session. The value is displayed in terms of kbps (Kilobits per second).
average_framerate_fps	long	The lifetime average rendered frame rate for the specific video session. The value is displayed in terms of fps (frames per second).
client_id	string	Client ID of the specific video session. The value is displayed in the format of four unsigned decimal integers separated by dots (.).
session_id	long	Session ID of the specific video session.
viewer_id	string	ID of the person watching this video. This is an identifier for a subscriber or subscription profile, but the exact semantics are determined by the device integration, not by Conviva.
stream_url	string	The manifest URL from which the video is loaded.
content_length_ms	long	The duration of the content that attempted to play during the session.
is_exit_before_video_start	string	Whether the user have left watching the video content before the video starts playing its first frame.
is_video_start_failure	string	Whether the user encounters difficulties initiating a video to play.
is_video_playback_failure	string	Whether the playback of a video is interrupted due to network instability, server downtimes, or any other problems in the content delivery network (CDN).
paused_time_ms	long	The duration the player has spent in the paused state over the session's lifetime till the end of the interval. The value is displayed in milliseconds and does not include time in the long paused state.
average_average_bitrate_bps	long	The duration of an interval metric. It represents the time-weighted average bitrates played on a particular player. The value does not include the bits when a video is paused or buffered. A higher value indicates a better viewer experience.
is_video_start_failure_business	string	Whether the initiation of a video to play is interrupted due to any business error.
is_video_playback_failure_business	string	Whether the playback of a video is interrupted due to any business error.
is_video_start_failure_tech	string	Whether the initiation of a video to play is interrupted due to any technical error.
is_video_playback_failure_tech	string	Whether the playback of a video is interrupted due to any technical error.
app_version	string	The version of the application on which a specific video session was played (appVersion).

Tags (Metadata)

Tags contain all the required and custom metadata.

Copy

"tags": 
{
            "appVersion": "5.0",
            "newtag": "somevalue",
            "media_player_framework_name": "ExoPlayer",
            "streamProtocol": "HLS",
            "device_type": "Desktop",
            "device_category": "Web",
            "device_operating_system_family": "macOS",
            "browser_version": "Chrome 128.0.0.0",
            "videoType": "VoD",
            "media_player_framework_version": "ExoPlayer 1.2.3",
            "device_os_version": "macOS 10.15.7",
            "device_model": "Mac",
            "device_manufacturer": "Apple",
            "serialName": "Anupama",
            "device_name": "Mac",
            "device_marketing_name": "Apple Mac",
            "expireDate": "28 October 2030",
            "connection_type": "2G",
            "demo_version": "2.0.0",
            "device_os": "macOS",
            "device_brand": "Chrome",
            "videoResolution": "1080 X 840",
}

Timeline Data

Timeline data shows session summary:

session_state
session_event
session_overview_event
bitrate
framerate
connection_type
cdn
asset
error
custom_event

Summary

Field	Datatype	Description
session_state	array of States	The playback state of the sessions in terms of epoch timestamp start_time_ms and end_time_ms. The possible session_state values are: Playing Buffering Rebuffering (Connection-Induced) Seek Induced Buffering Paused False Playing Play Long Buffering Long Paused Not Monitored Other
session_event	array of Events	A few types of events that are related to the playback SessionStartEvent, Seek, or FatalError with the respective epoch timestamp timeMs. For example, the Player Error or Fatal exception in AVPlayer error if occurred due to the VSF (Video Start Failure) and considered as a FatalError.
session_overview_event	array of Events	It represents smaller set of more significant event types, in a smaller timeline display. It can be the first time video played in a session or any fatal error that happened at an epoch.
bitrate	array of LinearStates	The bitrate that was playing, in kilobits per second (kbps).
framerate	array of LinearState	The approximate rate at which frames were being rendered, in frames per second. It shows the collection of epoch timestamp start_time_ms and end_time_ms associated to the start an end value of the framerates. For example, "start_value": 30 and "end_value": 30.
connection_type	array of States	Name of the last-hop connection (for example, WiFi, 3G) from the device to the Internet.
cdn	array of States	The name of the content delivery networks from which the device was receiving video data. It shows the collection of session epoch timestamp startTimeMs and endTimeMs associated to the content delivery networks (CDNs) (for example, AKAMAI, FIRSTLY, CLOUDFLARE).
asset	array of States	The name of the video asset that was being played in whatever raw format was reported by the device. It shows the collection of epoch timestamp startTimeMs and endTimeMs associated to the video assets.
error	array of Events	Any fatal or non-fatal error if occurred in a session. It shows the epoch timestamp of errorMessage, type, and whether the error is related to VSF causesVsf or VPF causesVpf.
custom_event	array of Events	Any event sent from the device through Conviva's custom events API. Also known as player insights events.

Event: It represents an instantaneous event at a certain point in time, carrying a value of type T.
Copy
```
{ 
"time_ms": instant_at_which_this_event_occurred, 
"value": payload_value_of_type_T 
}
```
State: It represents a single state the session had for some span of time, with state value T. By span we mean an uninterrupted time interval with a start and an end point. Consider a timeline (list) of State<T>s representing a step function or piecewise-constant function, from time to T.
Copy
```
{ 
"start_time_ms": start_of_this_span,
"end_time_ms": end_of_this_span, 
"value": payload_value_of_type_T 
}
```
LinearState: It represents the states a session had over some span of time, where the state is a number that evolves linearly from one value at the start of the span to another value at the end of the span. A timeline of these values represents a piecewise-linear function of time (from milliseconds to a state value) and would typically be displayed as a line plot.
Copy
```
{ 
"start_time_ms": start_of_this_span, 
"end_time_ms": end_of_this_span, 
"start_value": metric_value_at_start_of_this_span, 
"end_value": metric_value_at_end_of_this_span
}
```

Response Example (JSON)

Copy

{
    "summary_data": {
        "session_start_timestamp_ms": 1727076292216,
        "session_end_timestamp_ms": 1727078602419,
        "play_status": "Ended",
        "viewer_id": "view",
        "client_id": "1044508674.1778008252.324271753.1900824598",
        "session_id": 1934872955,
        "device_os": "macOS",
        "asset": "Test Validation Api",
        "app_name": "Android Exoplayer",
        "app_version": "5.0",
        "device_name": "Mac",
        "device_hardware_type": "Desktop",
        "device_os_family": "macOS",
        "browser_name": "Chrome",
        "browser_version": "Chrome 128.0.0.0",
        "content_length_ms": 1000000,
        "stream_url": "http://qthttp.apple.com.edgesuite.net/1010qwoeiuryfg/sl.m3u8",
        "tags": {
            "appVersion": "5.0",
            "c3.cws.clv": "4.7.2",
            "newtag": "somevalue",
            "media_player_framework_name": "ExoPlayer",
            "streamProtocol": "HLS",
            "device_type": "Desktop",
            "c3.cm.episodeNumber": "1",
            "c3.cm.seriesName": "Iron Man",
            "device_category": "Web",
            "device_operating_system_family": "macOS",
            "c3.device.ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36",
            "c3.cm.name": "CMS",
            "c3.cm.showTitle": "The one with all characters",
            "c3.cm.brand": "Marvel",
            "browser_version": "Chrome 128.0.0.0",
            "c3.device.conn": "2G",
            "c3.video.isLive": "F",
            "c3.adaptor.type": "eCws2",
            "videoType": "VoD",
            "c3.cfg.alt.name": "toggleEnable",
            "media_player_framework_version": "ExoPlayer 1.2.3",
            "c3.cm.genre": "Action",
            "c3.cm.categoryType": "Romance",
            "c3.cm.contentType": "Live",
            "device_os_version": "macOS 10.15.7",
            "c3.viewer.id": "view",
            "c3.cws.sf": "7",
            "c3.protocol.level": "2.6",
            "device_model": "Mac",
            "c3.cm.affiliate": "Dish",
            "c3.cm.channel": "Sony",
            "device_manufacturer": "Apple",
            "serialName": "Anupama",
            "device_name": "Mac",
            "device_marketing_name": "Apple Mac",
            "c3.sh": "qthttp.apple.com.edgesuite.net",
            "c3.cm.genreList": "Action, Romedy",
            "expireDate": "28 October 2030",
            "c3.cm.seasonNumber": "1",
            "c3.protocol.type": "cws",
            "connection_type": "2G",
            "demo_version": "2.0.0",
            "device_os": "macOS",
            "c3.player.name": "Android Exoplayer",
            "device_brand": "Chrome",
            "c3.cm.id": "40010",
            "videoResolution": "1080 X 840",
            "c3.device.usesSdk": "T",
            "c3.video.isAd": "F"
        },
        "video_start_time_ms": 1016,
        "playing_time_ms": 2181981,
        "paused_time_ms": 0,
        "rebuffering_time_ms": 0,
        "connection_induced_rebuffering_time_ms": "0",
        "average_peak_bitrate_bps": 320,
        "average_framerate_fps": 0,
        "average_average_bitrate_bps": 0,
        "is_exit_before_video_start": "false",
        "is_video_start_failure": "false",
        "is_video_playback_failure": "false",
        "is_video_start_failure_business": "false",
        "is_video_playback_failure_business": "false",
        "is_video_start_failure_tech": "false",
        "is_video_playback_failure_tech": "false"
    },
    "timeline_data": {
        "session_state": [
            {
                "start_time_ms": 1727076292228,
                "end_time_ms": 1727076292230,
                "value": "NotMonitored"
            },
            {
                "start_time_ms": 1727076292230,
                "end_time_ms": 1727076293232,
                "value": "Buffering"
            },
            {
                "start_time_ms": 1727076293232,
                "end_time_ms": 1727077767793,
                "value": "Playing"
            },
            {
                "start_time_ms": 1727077830000,
                "end_time_ms": 1727077837780,
                "value": "Playing"
            },
            {
                "start_time_ms": 1727077902779,
                "end_time_ms": 1727078602419,
                "value": "Playing"
            },
            {
                "start_time_ms": 1727078602419,
                "end_time_ms": 1727078602419,
                "value": "Other"
            }
        ],
        "session_event": [
            {
                "time_ms": 1727076292216,
                "value": "SessionStart"
            },
            {
                "time_ms": 1727076293232,
                "value": "Play"
            },
            {
                "time_ms": 1727078602419,
                "value": "End"
            }
        ],
        "session_overview_event": [
            {
                "time_ms": 1727076293232,
                "value": "Play"
            },
            {
                "time_ms": 1727078602419,
                "value": "End"
            }
        ],
        "bitrate": [
            {
                "start_time_ms": 1727076293233,
                "end_time_ms": 1727077767793,
                "start_value": 320.0,
                "end_value": 320.0
            },
            {
                "start_time_ms": 1727077830000,
                "end_time_ms": 1727077837780,
                "start_value": 320.0,
                "end_value": 320.0
            },
            {
                "start_time_ms": 1727077902779,
                "end_time_ms": 1727078602419,
                "start_value": 320.0,
                "end_value": 320.0
            }
        ],
        "framerate": [],
        "connection_type": [
            {
                "start_time_ms": 1727076292216,
                "end_time_ms": 1727077767793,
                "value": "2G"
            },
            {
                "start_time_ms": 1727077830000,
                "end_time_ms": 1727077837780,
                "value": "2G"
            },
            {
                "start_time_ms": 1727077902779,
                "end_time_ms": 1727078602419,
                "value": "2G"
            }
        ],
        "cdn": [
            {
                "start_time_ms": 1727076292216,
                "end_time_ms": 1727077767793,
                "value": "AKAMAI"
            },
            {
                "start_time_ms": 1727077830000,
                "end_time_ms": 1727077837780,
                "value": "AKAMAI"
            },
            {
                "start_time_ms": 1727077902779,
                "end_time_ms": 1727078602419,
                "value": "AKAMAI"
            }
        ],
        "asset": [
            {
                "start_time_ms": 1727076292216,
                "end_time_ms": 1727077767793,
                "value": "Test Validation Api"
            },
            {
                "start_time_ms": 1727077830000,
                "end_time_ms": 1727077837780,
                "value": "Test Validation Api"
            },
            {
                "start_time_ms": 1727077902779,
                "end_time_ms": 1727078602419,
                "value": "Test Validation Api"
            }
        ],
        "error": [],
        "custom_event": []
    }
}

SSD Timeline Event Mapping

Event SSD Key	Event SSD Sub-Field Key	Event SSD Value	Equivalent Key in Validation Timeline API	Equivalent Value in Validation Timeline API
convivaSessionId	N/A	N/A	summary_data.client_id:summary_data.session_id	N/A
timestampMs	N/A	N/A	timeline_data.session_state.start_time_ms timeline_data.session_event.time_ms timeline_data.session_overview_event.time_ms timeline_data.bitrate.start_time_ms timeline_data.framerate.start_time_ms timeline_data.connection_type.start_time_ms timeline_data.cdn.start_time_ms timeline_data.asset.start_time_ms timeline_data.error.time_ms timeline_data.custom_event.time_ms	N/A
eventType	N/A	0 1 2 3 4 5 6	timeline_data.session_state timeline_data.bitrate timeline_data.error timeline_data.cdn timeline_data.asset N/A timeline_data.custom_event	N/A
newPlayerState	N/A	1	timeline_data.session_event.value	End
	N/A	3		Playing FalsePlaying
	N/A	6		Buffering Rebuffering SeekInducedBuffering
	N/A	12		Paused LongPaused
	N/A	98		NotMonitored
	N/A	100		Other
newBitrate	N/A	N/A	timeline_data.bitrate.start_value	N/A
error_messages			timeline_data.error.value.error_message timeline_data.session_event.value.error_message	Any error messages like Player Error and others.
fatal	N/A	N/A	timeline_data.error.value.type timeline_data.session_event.value.type	Fatal Error
newCDN	N/A	N/A	timeline_data.cdn.value	N/A
newAsset	N/A	N/A	timeline_data.asset.value	N/A
customEvent	customEvent.name	Conviva.PodStart Conviva.PodEnd	timeline_data.custom_event.value.name	Conviva.PodStart Conviva.PodEnd
	customEvent.attributes	{"adType":"Server Side"} {"podPosition":"Mid-roll","adType":"Server Side","podIndex":"2"}	timeline_data.custom_event.value.attributes	{"adType":"Server Side"} {"podPosition":"Mid-roll","adType":"Server Side","podIndex":"2"}
	customEvent.pht	1345	N/A	N/A
eventTime	N/A	N/A	Same as timestamp_ms in Event SSD in YYYY-MM-DDTHH:MM:SS.SSS+0000 format	N/A

HTTP Response Codes

200-Success

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

Request	Response
Query with a valid viewer_id, session_id, or both. For example, v1/validation-timeline?viewer_id={“12345678”}&session_id={“-923452232”} v1/validation-timeline?session_id={“-923452232”} v1/validation-timeline?viewer_id={“12345678”}	Fetch the session summaries, event timelines, and metadata in JSON format for the given viewer_id and/or session_id.

Request

Response

Query with a valid viewer_id, session_id, or both.

For example,

v1/validation-timeline?viewer_id={“12345678”}&session_id={“-923452232”}

v1/validation-timeline?session_id={“-923452232”}

v1/validation-timeline?viewer_id={“12345678”}

Fetch the session summaries, event timelines, and metadata in JSON format for the given viewer_id and/or session_id.

4xx-Client-side Errors

Client-side error codes start with the number 4, for example, 400 (Bad Request), 401 (Unauthorized), 404 (Not Found).

Request	Response
Query with only NULL session_id For example: v1/validation-timeline?session_id={null}	417 - Exception Failed Please pass a valid 'viewer_id'/'session_id' or both in the request URL.

Request

Response

Query with only NULL session_id

For example:

v1/validation-timeline?session_id={null}

417 - Exception Failed

Please pass a valid 'viewer_id'/'session_id' or both in the request URL.

5xx-Server-side Errors

Server-side error codes start with the number 5, for example, 500 (Internal Server Error)..

Request	Response
Query with invalid viewer_id. For example: v1/validation-timeline?viewer_id={“123”}&session_id={“611124010”}	503 - Service Unavailable Error: No record found for viewerId: 123 and sessionId: 611124010. Please try again later. If the issue continues, please contact Conviva.
Query with invalid session_id. For example: v1/validation-timeline?viewer_id={“12345678”}&session_id={“123”}	503 - Service Unavailable Error: No record found for viewerId: 12345678 and sessionId: 123. Please try again later. If the issue continues, please contact Conviva.
Query with invalid viewer_id. For example: v1/validation-timeline?viewer_id={“123”}&session_id={“123”}	503 - Service Unavailable Error: No record found for viewerId: 123 and sessionId: 123. Please try again later. If the issue continues, please contact Conviva.

Request

Response

Query with invalid viewer_id.

For example:

v1/validation-timeline?viewer_id={“123”}&session_id={“611124010”}

503 - Service Unavailable

Error: No record found for viewerId: 123 and sessionId: 611124010. Please try again later. If the issue continues, please contact Conviva.

Query with invalid session_id.

For example:

v1/validation-timeline?viewer_id={“12345678”}&session_id={“123”}

503 - Service Unavailable

Error: No record found for viewerId: 12345678 and sessionId: 123. Please try again later. If the issue continues, please contact Conviva.

Query with invalid viewer_id.

For example:

v1/validation-timeline?viewer_id={“123”}&session_id={“123”}

503 - Service Unavailable

Error: No record found for viewerId: 123 and sessionId: 123. Please try again later. If the issue continues, please contact Conviva.

Validation Timeline API v1

Validation Timeline API (v1)

URLs

Method: GET

Security: HTTPS

Authentication

Content-Type

Response

Summary

Tags (Metadata)

Timeline Data

Summary

Response Example (JSON)

SSD Timeline Event Mapping

HTTP Response Codes