--- title: "List mouse events on a clip" method: GET path: "/v1/videos/{id}/clips/{clipId}/mouse-events" tags: ["Clips"] --- # List mouse events on a clip `GET /v1/videos/{id}/clips/{clipId}/mouse-events` ## Request - Base URL: `https://api.tella.com` - URL: `https://api.tella.com/v1/videos/{id}/clips/{clipId}/mouse-events` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns the cursor path and clicks recorded with the clip's screen recording, mapped onto the clip's playback timeline (cuts applied). Positions are percentages of the screen recording's dimensions — the same coordinate space as zoom focus points. Events during cut-out footage are dropped, and move events are sampled (default one per 100ms, `intervalMs=0` for every event). Use `types=clicks` to return only clicks. Returns an empty list when the recording has no mouse data (camera-only clips, uploads, older recorder versions). Pass `startTimeMs`/`endTimeMs` to read a long recording in windows; a window returns the same events the whole-clip response has in that range. ## Path parameters - `id` string, required: Video identifier - `clipId` string, required: Clip identifier ## Query parameters - `startTimeMs` integer: Only return items at or after this time, in ms on the clip's playback timeline. Defaults to the clip's start. - `endTimeMs` integer: Only return items before this time (exclusive), in ms on the clip's playback timeline. Must be greater than `startTimeMs`. Defaults to the clip's end. Page through a long clip with windows that meet end to start. - `intervalMs` integer: Thin move events to at most one per this many ms of playback — clicks are always kept. Defaults to 100. Pass 0 for every recorded event (can be tens of thousands on long recordings). - `types` string: Comma-separated event kinds to return: clicks, moves. Default: both. Use types=clicks for the positions where a mouse button went down — one event per press, not one per sample of a held button. ## Response `200` OK - ListClipMouseEventsResponse: Mouse events from the clip's screen recording. Empty when the recording has no mouse data (camera-only clips, uploads, older recorder versions). - `events` ClipMouseEvent[], required - `clicked` boolean, required: True when a mouse button went down at this event. Recordings sample the button state continuously, so a drag reports true only on the initial press — the samples while the button stays held are returned as move events. - `isLocalEvent` boolean, required: True when the event happened inside Tella's own recorder UI (e.g. the recording controls) rather than the recorded content - `timestampMs` number, required: Time in ms on the clip's playback timeline (cuts applied) - `xPct` number, required: Horizontal cursor position as a percentage of the screen recording's width (0-100) — the same coordinate space as zoom focus points. - `yPct` number, required: Vertical cursor position as a percentage of the screen recording's height (0-100) ## 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 > 72 revisions in range; 1 not diffed. - **2026-09-29** `704d6fc3bc60`: 2 info - added the new optional `query` request parameter `endTimeMs` - added the new optional `query` request parameter `startTimeMs` - **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-09** `6b1132ef42fb`: 14 warning, 2 info - added the new `conflict` enum value to the `error` response property for the response status `400` - added the new `conflict` enum value to the `error` response property for the response status `401` - added the new `conflict` enum value to the `error` response property for the response status `403` - added the new `conflict` enum value to the `error` response property for the response status `404` - …12 more [Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/mouse-events/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/ca74daaf9201?raw)