---
title: "Search videos"
method: GET
path: "/v1/videos/search"
tags: ["Videos"]
---

# Search videos

`GET /v1/videos/search`

Search the authenticated user's direct video library by title or indexed transcript sentences.

## Query parameters

- `query` string, required — Words to find in video titles or indexed transcript sentences
- `searchIn` 'all' | 'title' | 'transcript' — Fields to search (default: all)
- `limit` integer — Upper bound on results per page (default: 20, max: 100). A page can be shorter once results the caller cannot see are removed, so keep paging while hasMore is true.
- `cursor` string — Opaque pagination cursor from the previous response

## Response `200`

Matching videos

- SearchVideosResponse
  - `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.
  - `results` SearchVideoResult[], required
    - `matches` SearchMatch[], required
      - `endSeconds` number, nullable, required — End of the matching transcript sentence, in seconds. Null for title matches.
      - `field` 'title' | 'transcript', required
      - `matchedTokens` string[], required
      - `snippet` string, required — Plain-text matching excerpt
      - `startSeconds` number, nullable, required — Start of the matching transcript sentence, in seconds. Null for title matches.
    - `video` VideoListItem, required — Video item in a list response
      - `aspectRatio` string, required — Video aspect ratio (e.g., '16:9', '9:16')
      - `autoRatio` boolean, required — Whether the canvas is in Auto ratio (sized from the video's recording and following it as layouts change), the editor's Setup → Size → Auto.
      - `createdAt` string, date-time, required — ISO 8601 datetime
      - `description` string, required — Video description
      - `dimensions` object, required — Canvas size in pixels
        - `height` number, required
        - `width` number, required
      - `id` string, required — Unique video identifier
      - `links` VideoLinks, required — URLs related to a video
        - `embedPage` string, uri, required — URL for embedding the video
        - `viewPage` string, uri, required — URL to view the video on Tella
      - `name` string, required — Video title
      - `updatedAt` string, date-time, required — ISO 8601 datetime
      - `views` integer, required — Total view count

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

> 18 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-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
- **2026-09-02** `cd69045c703a` — 1 info
  - added the required property `results/items/video/autoRatio` to the response with the `200` status

[Change history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/search/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/704d6fc3bc60?raw)