---
title: "Get video analytics"
method: GET
path: "/v1/videos/{id}/analytics"
tags: ["Analytics"]
---

# Get video analytics

`GET /v1/videos/{id}/analytics`

Viewing analytics for one video: plays, unique sessions, watch time, plays per day, retention per one-percent slice, geography, referrers, UTM traffic sources, and call-to-action clicks. Available to the video's creator, its collaborators, and workspace members it is shared with. Dates are whole UTC days; omit both for all time.

## Path parameters

- `id` string, required — Unique video identifier

## Query parameters

- `startDate` string — First day of the range, inclusive, as YYYY-MM-DD in UTC. Omit to start from the first recorded view.
- `endDate` string — Last day of the range, inclusive, as YYYY-MM-DD in UTC. Omit to run through today.
- `timezone` string — IANA time zone used to bucket viewsOverTime into days (default: UTC)

## Response `200`

OK

- VideoAnalyticsResponse — Viewing analytics for one video
  - `ctaClicks` integer, required — Clicks on the video's call-to-action button in the range
  - `endDate` string, nullable, required — The endDate that was applied, or null for no upper bound
  - `geoBreakdown` AnalyticsGeoPoint[], required — Plays by country, up to 100 rows by views
    - `country` string, nullable, required — ISO 3166-1 alpha-2 country code; null when unknown
    - `uniqueSessions` integer, required
    - `views` integer, required
  - `referrerBreakdown` AnalyticsReferrerPoint[], required — Plays by referring domain, up to 100 rows by views
    - `referrerDomain` string, nullable, required — Domain the viewer arrived from; null for direct or unknown traffic
    - `uniqueSessions` integer, required
    - `views` integer, required
  - `retention` AnalyticsRetentionPoint[], required — Watch counts per one-percent slice of the video, ascending
    - `percent` integer, required — Position in the video as a percentage of its duration
    - `uniqueViewers` integer, required — Distinct viewers who watched this slice
    - `watchCount` integer, required — Times this one-percent slice was watched, including replays by the same viewer
  - `startDate` string, nullable, required — The startDate that was applied, or null for no lower bound
  - `summary` AnalyticsSummary, required — Headline viewing metrics
    - `avgPercentViewed` number, nullable, required — Average share of the video watched per play, from 0 to 100. Null when nothing was watched in the range.
    - `pageOpens` integer, required — Times the video page was opened, whether or not playback started
    - `totalViews` integer, required — Plays in the range. A play is counted once a viewer starts the video.
    - `totalWatchTimeSeconds` number, required — Total time viewers spent watching, in seconds
    - `uniqueSessions` integer, required — Distinct viewer sessions that started a play
  - `timezone` string, required — Time zone used to bucket viewsOverTime
  - `trafficSources` AnalyticsTrafficSourcePoint[], required — Plays by UTM source, medium and campaign, up to 100 rows by views
    - `campaign` string, required — utm_campaign, or an empty string when not set
    - `medium` string, required — utm_medium, or an empty string when not set
    - `source` string, required — utm_source when the link carried one, otherwise the referrer domain, otherwise "direct"
    - `uniqueSessions` integer, required
    - `views` integer, required
  - `videoId` string, required
  - `viewsOverTime` AnalyticsViewsPoint[], required — Plays per day, ascending
    - `date` string, required — Day as YYYY-MM-DD in the requested timezone
    - `uniqueSessions` integer, required — Distinct viewer sessions that day
    - `views` integer, required — Plays that day

## Other responses

- `400` — The request was malformed or contained invalid parameters.
- `401` — Authentication is required. Provide a valid API key.
- `403` — You don't have permission to access this resource.
- `404` — The requested resource was not found.
- `409` — The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429` — You have exceeded the rate limit. Please slow down.
- `500` — An unexpected error occurred
- `501` — The requested operation is not implemented.
- `503` — A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 19 revisions in range; 1 not diffed.

- **2026-09-28** `ac47c99c144f` — 9 warning
  - added the new `edit_conflict` enum value to the `error` response property for the response status `400`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `401`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `403`
  - added the new `edit_conflict` enum value to the `error` response property for the response status `404`
  - …5 more
- **2026-09-13** `6bf5f3a6bf73` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/analytics/get.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) · [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/d3eafbc27bf9?raw)