Get watchtime and engagement metrics for VODs or live channels
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Get watchtime and engagement metrics for VODs or live channels on your account.
GET /v2/analytics/vod/watchtime-engagement
GET /v2/analytics/live/watchtime-engagement
A successful call returns 200 and a JSON object with a results array. Each row is one content × period aggregate (month by default, or day when granularity=day). A period with no data returns 200 with "results": [] (not 404).
Content IDs
- Optional filter:
content-ids— comma-separated UUIDs (with or without thevod-/live-prefix). Omit to return all VODs or live channels on the account for the chosen path. - Response
content-idvalues include the prefix (for examplevod-28cfe183-675c-4aa5-95d6-3cf5260d92c6orlive-011c2dd4-765b-474d-980b-aced9b8cd0c1).
Query parameters
| Name | Type | Description |
|---|---|---|
startdate | string | Start of the range, YYYY-MM-DD only. Default: 30 days before the request time. |
enddate | string | End of the range, YYYY-MM-DD only (inclusive). Default: request time. |
timezone | string | IANA timezone used to interpret startdate / enddate (default UTC, for example America/New_York). |
granularity | string | day or month. Default: month. |
page | integer | Page number (default 1). |
perPage | integer | Rows per page (default 100). Each row is one content × period combination. |
content-ids | string | Optional comma-separated VOD or live channel UUIDs to filter. |
Date behavior
- Only
YYYY-MM-DDis accepted. Other formats return 400 (startdate must be YYYY-MM-DD/enddate must be YYYY-MM-DD). startdatemust be on or beforeenddate(same-day ranges are valid and inclusive).- For
granularity=month, the requested range cannot exceed 366 days (otherwise 400). - With
granularity=month(default), rows useperiodasYYYY-MM. Withgranularity=day,periodisYYYY-MM-DD. period-start/period-endon each row are clipped to the requested range (so a partial month does not look like a full calendar month).
Response fields
| Field | Description |
|---|---|
period | Bucket for the row: YYYY-MM (month grain) or YYYY-MM-DD (day grain). |
period-start | Inclusive start date covered by this row (clipped to the request). |
period-end | Inclusive end date covered by this row (clipped to the request). |
content-id | Prefixed content id (vod- or live- + UUID). |
title | Content title when available; "deleted" for removed assets. |
total-plays | Total play count for that content in that period. |
unique-viewers | Unique viewer count for that content in that period. |
total-watch-time | Total watch time in seconds. |
total-playtime | Total play time in seconds (includes freezes and buffering). |
avg-watch-time-per-viewer | total-watch-time / unique-viewers in seconds (0 when unique-viewers is 0). |
completion-rate | engagement-100 / total-plays * 100. |
bytes-consumed | CDN bytes consumed for that content in that period. |
engagement-10 … engagement-100 | Plays whose furthest point peaked near that % of duration (not cumulative). See Engagement buckets below. |
Engagement buckets
Each engagement-N counts plays whose furthest watched point on the VOD reached about N% of duration (small duration tolerance applied). Buckets are not a cumulative funnel: a play that reached 100% increments engagement-100 only — it is not also added to engagement-10 … engagement-90.
completion-rate = engagement-100 / total-plays * 100.
Example with total-plays: 2: one play peaked near 50%, one near 100% → engagement-50: 1, engagement-100: 1, completion-rate: 50. The sum of buckets can be less than total-plays when duration/progress is missing. For live, buckets are typically all 0.
Example (2 plays: one peaked near 50%, one near 100%):
{
"total-plays": 2,
"engagement-10": 0,
"engagement-25": 0,
"engagement-50": 1,
"engagement-75": 0,
"engagement-90": 0,
"engagement-100": 1,
"completion-rate": 50
}