> ## Documentation Index > Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get workspace 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. ## OpenAPI ````yaml /openapi.json get /v1/analytics openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 100 requests per minute per user within a workspace. Rate limit information is returned in response headers: - `RateLimit-Policy`: Named quota, request limit, and window in seconds - `RateLimit`: Remaining quota and seconds until reset - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets A `429 Too Many Requests` response also includes `Retry-After` in seconds. title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: >- Viewing analytics for a video or across the workspace: plays, watch time, retention, geography, referrers name: Analytics - description: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect and background music catalogs — the same items the editor's media panels show name: Library - description: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/analytics: get: tags: - Analytics summary: Get workspace analytics description: >- 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. operationId: getWorkspaceAnalytics parameters: - description: >- First day of the range, inclusive, as YYYY-MM-DD in UTC. Omit to start from the first recorded view. in: query name: startDate schema: description: >- First day of the range, inclusive, as YYYY-MM-DD in UTC. Omit to start from the first recorded view. example: '2026-01-01' pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: >- Last day of the range, inclusive, as YYYY-MM-DD in UTC. Omit to run through today. in: query name: endDate schema: description: >- Last day of the range, inclusive, as YYYY-MM-DD in UTC. Omit to run through today. example: '2026-01-01' pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: 'IANA time zone used to bucket viewsOverTime into days (default: UTC)' in: query name: timezone schema: description: >- IANA time zone used to bucket viewsOverTime into days (default: UTC) example: America/New_York type: string - description: 'Which videos to aggregate (default: workspace)' in: query name: scope schema: allOf: - $ref: '#/components/schemas/AnalyticsScope' description: 'Which videos to aggregate (default: workspace)' - description: 'Top videos per page (default: 20, max: 100)' in: query name: limit schema: description: 'Top videos per page (default: 20, max: 100)' example: 20 maximum: 100 minimum: 1 type: integer - description: >- Opaque cursor for the next page of top videos, from the previous response's pagination.nextCursor in: query name: cursor schema: description: >- Opaque cursor for the next page of top videos, from the previous response's pagination.nextCursor type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/WorkspaceAnalyticsResponse' description: OK headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': content: application/json: example: docsUrl: https://docs.tella.com/ error: bad_request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: example: docsUrl: https://docs.tella.com/ error: unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: example: docsUrl: https://docs.tella.com/ error: forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '409': content: application/json: example: docsUrl: https://docs.tella.com/ error: conflict message: >- 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. schema: $ref: '#/components/schemas/ErrorResponse' description: >- 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. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: example: docsUrl: https://docs.tella.com/ error: rate_limited message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Retry-After: $ref: '#/components/headers/RetryAfter' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '500': content: application/json: example: docsUrl: https://docs.tella.com/ error: server_error message: An unexpected error occurred schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '501': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_implemented message: The requested operation is not implemented. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested operation is not implemented. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '503': content: application/json: example: docsUrl: https://docs.tella.com/ error: unavailable message: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. schema: $ref: '#/components/schemas/ErrorResponse' description: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' security: - BearerAuth: [] components: schemas: AnalyticsScope: description: >- workspace: every video shared with the workspace. mine: videos the authenticated user created. enum: - workspace - mine example: workspace type: string WorkspaceAnalyticsResponse: additionalProperties: false description: >- Viewing analytics aggregated across the workspace's videos. Everything except topVideos covers the whole scope; only topVideos is paginated. properties: endDate: description: The endDate that was applied, or null for no upper bound nullable: true type: string geoBreakdown: description: Plays by country, up to 100 rows by views items: $ref: '#/components/schemas/AnalyticsGeoPoint' type: array pagination: $ref: '#/components/schemas/Pagination' referrerBreakdown: description: Plays by referring domain, up to 100 rows by views items: $ref: '#/components/schemas/AnalyticsReferrerPoint' type: array retention: description: Watch counts per one-percent slice of the video, ascending items: $ref: '#/components/schemas/AnalyticsRetentionPoint' type: array scope: $ref: '#/components/schemas/AnalyticsScope' startDate: description: The startDate that was applied, or null for no lower bound nullable: true type: string summary: $ref: '#/components/schemas/AnalyticsSummary' timezone: description: Time zone used to bucket viewsOverTime example: UTC type: string topVideos: description: Videos ranked by plays in the range, descending items: $ref: '#/components/schemas/AnalyticsTopVideo' type: array viewsOverTime: description: Plays per day, ascending items: $ref: '#/components/schemas/AnalyticsViewsPoint' type: array required: - scope - startDate - endDate - timezone - summary - viewsOverTime - retention - geoBreakdown - referrerBreakdown - topVideos - pagination type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: docsUrl: description: Link to Tella API documentation example: https://docs.tella.com/ format: uri type: string error: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - rate_limited - server_error - conflict - not_implemented - unavailable example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object AnalyticsGeoPoint: additionalProperties: false properties: country: description: ISO 3166-1 alpha-2 country code; null when unknown example: US nullable: true type: string uniqueSessions: maximum: 9007199254740991 minimum: -9007199254740991 type: integer views: maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - country - views - uniqueSessions type: object Pagination: additionalProperties: false description: >- Pagination metadata for list responses. Results are sorted by updatedAt descending. properties: hasMore: description: Whether there are more items to fetch example: true type: boolean nextCursor: description: >- 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. example: eyJpZCI6IjEyMyJ9 nullable: true type: string required: - nextCursor - hasMore type: object AnalyticsReferrerPoint: additionalProperties: false properties: referrerDomain: description: Domain the viewer arrived from; null for direct or unknown traffic example: linkedin.com nullable: true type: string uniqueSessions: maximum: 9007199254740991 minimum: -9007199254740991 type: integer views: maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - referrerDomain - views - uniqueSessions type: object AnalyticsRetentionPoint: additionalProperties: false description: >- How often each one-percent slice of the video was watched. Slices with no views are omitted. properties: percent: description: Position in the video as a percentage of its duration example: 42 maximum: 100 minimum: 0 type: integer uniqueViewers: description: Distinct viewers who watched this slice maximum: 9007199254740991 minimum: -9007199254740991 type: integer watchCount: description: >- Times this one-percent slice was watched, including replays by the same viewer maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - percent - watchCount - uniqueViewers type: object AnalyticsSummary: additionalProperties: false description: Headline viewing metrics properties: avgPercentViewed: description: >- Average share of the video watched per play, from 0 to 100. Null when nothing was watched in the range. example: 63.5 nullable: true type: number pageOpens: description: Times the video page was opened, whether or not playback started example: 1610 maximum: 9007199254740991 minimum: -9007199254740991 type: integer totalViews: description: >- Plays in the range. A play is counted once a viewer starts the video. example: 1280 maximum: 9007199254740991 minimum: -9007199254740991 type: integer totalWatchTimeSeconds: description: Total time viewers spent watching, in seconds example: 48210.4 type: number uniqueSessions: description: Distinct viewer sessions that started a play example: 940 maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - totalViews - uniqueSessions - avgPercentViewed - totalWatchTimeSeconds - pageOpens type: object AnalyticsTopVideo: additionalProperties: false properties: avgPercentViewed: description: Average share of the video watched per play, 0 to 100 example: 71.2 type: number name: description: >- Video title; null when the video has since been deleted but its views remain counted example: Q3 product update nullable: true type: string uniqueSessions: maximum: 9007199254740991 minimum: -9007199254740991 type: integer videoId: example: vid_abc123def456 type: string views: maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - videoId - name - views - uniqueSessions - avgPercentViewed type: object AnalyticsViewsPoint: additionalProperties: false properties: date: description: Day as YYYY-MM-DD in the requested timezone example: '2026-01-14' type: string uniqueSessions: description: Distinct viewer sessions that day maximum: 9007199254740991 minimum: -9007199254740991 type: integer views: description: Plays that day maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - date - views - uniqueSessions type: object headers: Deprecation: description: Indicates that an API operation is deprecated, following RFC 9745 example: '@1767225600' schema: type: string RateLimit: description: >- Current quota with remaining requests (`r`) and seconds until reset (`t`) example: '"public-api";r=95;t=42' schema: type: string RateLimitPolicy: description: >- Named quota policy with the request limit (`q`) and window in seconds (`w`) example: '"public-api";q=100;w=60' schema: type: string Sunset: description: >- Indicates when a deprecated API operation will become unavailable, following RFC 8594 example: Tue, 30 Jun 2026 23:59:59 GMT schema: type: string XRateLimitLimit: description: Maximum requests allowed in the current window example: 100 schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window example: 95 schema: type: integer XRateLimitReset: description: Unix timestamp in milliseconds when the window resets example: 1704067200000 schema: format: int64 type: integer RetryAfter: description: Seconds to wait before retrying a rate-limited request example: 45 schema: minimum: 1 type: integer securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Model Context Protocol (MCP)](/docs/mcp-server.md) - [Get video analytics](/docs/api-reference/analytics/get-video-analytics.md) - [Video analytics](/docs/help/sharing/analytics.md) - [Refer and earn](/docs/help/referrals/refer-and-earn.md) - [Move videos to another workspace or account](/docs/help/admin/move-videos-between-workspaces.md)