---
title: "List key presses on a clip"
method: GET
path: "/v1/videos/{id}/clips/{clipId}/key-events"
tags: ["Clips"]
---

# List key presses on a clip

`GET /v1/videos/{id}/clips/{clipId}/key-events`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/videos/{id}/clips/{clipId}/key-events`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/videos/:id/clips/:clipId/key-events/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the keys pressed during the clip's screen recording, mapped onto the clip's playback timeline (cuts applied): each key going down or up with the modifiers held (such as command+C), and each change in held modifiers. Keys typed into Tella's own window are left out, and only the key's label is returned, never the typed characters. Key presses can reveal what was typed, so only the video's creator and editors can read them. Only Mac app recordings capture the keyboard; other clips return an empty list. Pass `startTimeMs`/`endTimeMs` to read a window.

## 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.

## Response `200`

OK

- ListClipKeyEventsResponse: Key presses from the clip's screen recording. Empty when the recording has no keyboard data (only the Mac app records it).
  - `events` ClipKeyEvent[], required
    - `isRepeat` boolean, required: An auto-repeat while the key is held down
    - `key` string, nullable, required: The key's label, such as `C`, `Return` or `→`. Null on `modifiersChanged`.
    - `kind` 'down' | 'up' | 'modifiersChanged', required: `down`/`up` for a key press and release, `modifiersChanged` when the set of held modifiers changes.
    - `modifiers` string[], required: Modifiers held with the key; on `modifiersChanged`, the full set now held.
    - `timestampMs` number, required: Time in ms on the clip's playback timeline (cuts applied)

## 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-10-19** `262faf10b353`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/clips/:clipId/key-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)