--- title: "Get workspace analytics" method: GET path: "/v1/analytics" tags: ["Analytics"] --- # Get workspace analytics `GET /v1/analytics` Viewing analytics aggregated across videos: by default every video shared with the workspace, or with scope=mine only the videos you created. Includes the same summary, plays per day, retention, geography and referrer breakdowns as a single video, plus the videos ranked by plays. Only topVideos is paginated; pass pagination.nextCursor as cursor for the next page. Dates are whole UTC days; omit both for all time. ## 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) - `scope` 'workspace' | 'mine' — workspace: every video shared with the workspace. mine: videos the authenticated user created. - `limit` integer — Top videos per page (default: 20, max: 100) - `cursor` string — Opaque cursor for the next page of top videos, from the previous response's pagination.nextCursor ## Response `200` OK - WorkspaceAnalyticsResponse — Viewing analytics aggregated across the workspace's videos. Everything except topVideos covers the whole scope; only topVideos is paginated. - `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 - `pagination` Pagination, required — Pagination metadata for list responses. Results are sorted by updatedAt descending. - `hasMore` boolean, required — Whether there are more items to fetch - `nextCursor` string, nullable, required — Cursor for next page. Pass this value as the 'cursor' query parameter to fetch the next page. Null if no more pages. This is an opaque value - do not decode or modify it. - `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 - `scope` 'workspace' | 'mine', required — workspace: every video shared with the workspace. mine: videos the authenticated user created. - `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 - `topVideos` AnalyticsTopVideo[], required — Videos ranked by plays in the range, descending - `avgPercentViewed` number, required — Average share of the video watched per play, 0 to 100 - `name` string, nullable, required — Video title; null when the video has since been deleted but its views remain counted - `uniqueSessions` integer, required - `videoId` string, required - `views` integer, 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/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)