> ## Documentation Index > Fetch the complete documentation index at: https://docs.trackplay.io/llms.txt > Use this file to discover all available pages before exploring further. # List a video's raw events > The raw, auditable event stream for one video: every play, pause, ended, and conversion, one row at a time. No vanity metric sits on top of it. This endpoint is paginated. Read `events.total` for the count, then walk the pages with `page` and `per_page`. `ip_hash` is always `null` in the API response. Requires a token with the `analytics:read` scope. Server: `https://app.trackplay.io/api/v1` ## OpenAPI ````yaml /api-reference/openapi.json get /videos/{video}/analytics/events openapi: 3.1.0 info: title: TrackPlay API description: >- Send conversions and events to TrackPlay, and read them back. Authenticated with scoped tokens you mint in the dashboard. version: 1.0.0 servers: - url: https://app.trackplay.io/api/v1 description: App API. Conversions, videos, webhooks. - url: https://e.trackplay.io description: Events API. High-volume event ingest. security: - bearerAuth: [] paths: /videos/{video}/analytics/events: get: tags: - Analytics summary: List a video's raw events description: >- The raw, auditable event stream for one video: every play, pause, ended, and conversion, one row at a time. No vanity metric sits on top of it. This endpoint is paginated. Read `events.total` for the count, then walk the pages with `page` and `per_page`. `ip_hash` is always `null` in the API response. Requires a token with the `analytics:read` scope. Server: `https://app.trackplay.io/api/v1` operationId: getVideoAnalyticsEvents parameters: - name: video in: path required: true schema: type: integer description: The video's numeric ID. - name: from in: query required: false schema: type: string format: date description: Start of the range, as an ISO date. Defaults to 7 days ago. - name: to in: query required: false schema: type: string format: date description: End of the range, as an ISO date. Defaults to today. - name: tz in: query required: false schema: type: string default: UTC description: Timezone the range is read in, as an IANA name. Defaults to `UTC`. - name: event_type in: query required: false schema: type: string description: >- Return only this event type, e.g. `play`, `pause`, `ended`, or `conversion`. Omit to return every type. - name: page in: query required: false schema: type: integer default: 1 description: Which page to return. Defaults to 1. - name: per_page in: query required: false schema: type: integer default: 100 maximum: 500 description: Rows per page. Defaults to 100. Capped at 500. responses: '200': description: One page of events. content: application/json: schema: $ref: '#/components/schemas/EventsResponse' examples: events: value: video_id: 481 page: 1 per_page: 100 events: total: 4812 data: - event_type: play event: video-play session_code: 3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22 watch_seconds: 0 video_time: 0 created_at: '2026-07-16T14:02:11Z' ip_hash: null - event_type: conversion event: conversion session_code: 3b1e5c90-77aa-4f2d-8c31-6de0a9b41c22 watch_seconds: 268 video_time: 214 created_at: '2026-07-16T14:06:39Z' ip_hash: null '401': description: >- `AUTH_REQUIRED`: no token sent. `INVALID_TOKEN`: the token is invalid, expired, or revoked. content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: '`INSUFFICIENT_SCOPE`: the token does not carry `analytics:read`.' content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: No video with that ID exists in this workspace. content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: >- Validation failed. A date could not be parsed, `to` fell before `from`, or `per_page` was out of range. '429': description: Rate limited. Reads are capped at 600 requests per minute per token. components: schemas: EventsResponse: type: object properties: video_id: type: integer page: type: integer description: The page returned. per_page: type: integer description: Rows per page. events: type: object properties: total: type: integer description: >- Total rows across every page. Use it to know when you have read them all. data: type: array items: type: object properties: event_type: type: string description: >- The event category, e.g. `play`, `pause`, `ended`, `conversion`. event: type: string description: The raw event name as it was stored. session_code: type: string description: The viewer's session this event belongs to. watch_seconds: type: - number - 'null' description: >- Seconds watched at the moment of the event. `null` when it does not apply. video_time: type: - number - 'null' description: >- Position in the video, in seconds, at the moment of the event. `null` when it does not apply. created_at: type: string description: When the event was recorded. ip_hash: type: 'null' description: Always `null` in the API response. ApiError: type: object description: The error shape the app API returns on a failed read or export. properties: error: type: object properties: code: type: string description: >- A stable error code, e.g. `INSUFFICIENT_SCOPE`, `VIDEO_NOT_FOUND`, `EXPORT_NOT_FOUND`. message: type: string description: What went wrong, in plain English. securitySchemes: bearerAuth: type: http scheme: bearer description: >- A scoped token minted in **Settings → API tokens**. Send it as `Authorization: Bearer tplt_…` or `X-API-Key: tplt_…`. ````