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

# List text overlays on a clip

`GET /v1/videos/{id}/clips/{clipId}/text-overlays`

## Request

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

Returns the text overlays on a clip.

## Path parameters

- `id` string, required: Video identifier
- `clipId` string, required: Clip identifier

## Response `200`

OK

- ListClipTextOverlaysResponse: Text overlays on a clip
  - `textOverlays` ClipTextOverlay[], required
    - `animation` OverlayAnimation, required: How the overlay enters and leaves, like the editor's Animate panel. When set it replaces `transition`.
      - `intro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', required: How a side accelerates. `linear` keeps one speed. `smooth`, `natural`, `slow_down`, `accelerate`, `elastic`, `bounce`, `overshoot`, `impulse` and `swing` are shaped by `intensity`. `custom` follows `bezier`, `spring` follows `spring`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `moveX` number, required: Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.
        - `moveY` number, required: Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
      - `motionBlur` boolean, required: Blur the overlay along its motion while it moves, scales or turns.
      - `outro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', required: How a side accelerates. `linear` keeps one speed. `smooth`, `natural`, `slow_down`, `accelerate`, `elastic`, `bounce`, `overshoot`, `impulse` and `swing` are shaped by `intensity`. `custom` follows `bezier`, `spring` follows `spring`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `moveX` number, required: Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.
        - `moveY` number, required: Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
      - `textIntro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', required: How a side accelerates. `linear` keeps one speed. `smooth`, `natural`, `slow_down`, `accelerate`, `elastic`, `bounce`, `overshoot`, `impulse` and `swing` are shaped by `intensity`. `custom` follows `bezier`, `spring` follows `spring`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `moveX` number, required: Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.
        - `moveY` number, required: Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
      - `textOutro` OverlayAnimationSide, required: One side of an overlay animation: the hidden state the overlay moves from on the way in, or back to on the way out.
        - `blur` number, required: Blur of the hidden state in pixels.
        - `clip` boolean, required: Clip the motion to the overlay's box, so it wipes in like a mask.
        - `durationMs` integer, required: How long the side plays, in ms (50 to 5000). On a text side, how long each unit plays.
        - `easing` OverlayAnimationEasing, required
          - `bezier` union[]: The `custom` curve's handles.
            - union
              - …
          - `curve` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'bounce' | 'overshoot' | 'impulse' | 'swing' | 'custom' | 'spring', required: How a side accelerates. `linear` keeps one speed. `smooth`, `natural`, `slow_down`, `accelerate`, `elastic`, `bounce`, `overshoot`, `impulse` and `swing` are shaped by `intensity`. `custom` follows `bezier`, `spring` follows `spring`.
          - `intensity` number, required: How strongly the curve shapes the motion, 0 to 1. Only curves with an intensity use it.
          - `spring` OverlayAnimationSpringOutput: Spring physics. The spring sets the side's `durationMs`: it lasts until the spring comes to rest.
            - `damping` number, required
            - `mass` number, required
            - `stiffness` number, required
        - `moveX` number, required: Horizontal offset of the hidden state, as a fraction of the overlay's width (of a line's height on a text side); positive is right.
        - `moveY` number, required: Vertical offset of the hidden state, as a fraction of the overlay's height (of a line's height on a text side); positive is down.
        - `opacity` number, required: Opacity of the hidden state, 0 to 1.
        - `preset` 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'mask_up' | 'mask_down' | 'grow' | 'shrink' | 'blur' | 'blur_slide_up', required: A ready-made side, the same as the editor's Animate presets. A `slide_*` or `mask_*` arrow is the direction the overlay travels, so a `slide_up` intro rises into place and a `slide_up` outro rises away.
        - `rotate` number, required: Clockwise rotation of the hidden state in degrees.
        - `scale` number, required: Scale of the hidden state; 1 is its resting size.
        - `text` OverlayAnimationText: The units a text side plays on, each in turn.
          - `delayMs` integer, required: How long after one unit the next starts, in ms (0 to 2000).
          - `order` 'forward' | 'backward' | 'center' | 'edges' | 'random', required: Which unit goes first. `random` uses the same shuffle every time.
          - `smoothing` 'linear' | 'smooth' | 'natural' | 'slow_down' | 'accelerate' | 'elastic' | 'overshoot' | 'impulse' | 'swing', required: Eases the delays across the units: `linear` is an even step, the other curves bunch the starts up at one end.
          - `unit` 'letters' | 'words' | 'lines', required: What animates on its own.
    - `background` TextOverlayBackgroundOutput, required: Background behind a text overlay, in the same object shape as a clip background.
      - `color` string, required: Hex color string. Required when type = 'solid'. Transparent backgrounds use #00000000.
      - `type` 'solid', required: Background variant. Text overlays take a solid background; the other `ClipBackground` variants are not supported behind text.
    - `backgroundPadding` number, required: Extra room around the text inside its background, as a fraction of the font size added on every side (0.5 at an 80px font adds 40px). 0 is the standard padding. No effect without a visible background.
    - `backgroundShape` 'none' | 'regular' | 'squircle', required: Shape of the solid background behind the text.
    - `color` string, required: Hex color in #RRGGBB or #RRGGBBAA form. Responses use uppercase #RRGGBBAA.
    - `depth` 'front' | 'behind_presenter', required: Where the overlay sits relative to the presenter: the person in the clip's camera recording, or in its uploaded footage when the clip has no camera. `front` paints over everything. `behind_presenter` paints it behind the person but over everything else: in any layout the person is matted out of their footage and redrawn above the overlay. Fullscreen and framed layouts keep the recorded room around them; a cut-out layout replaces the room with the clip background. New overlays start on `front`. Without a presenter the overlay paints in front either way.
    - `depthChanges` object[]: Changes of `depth` over the overlay's own time, each held until the next: `atMs` after the overlay starts it moves to that depth, so one overlay can pass in front of the presenter and back behind them (a ring orbiting their head, a title they step in front of). `depth` is where it starts. On updates, omit it to leave the changes as they are; `[]` removes them. Absent in responses while the overlay holds one depth.
      - `atMs` number, required: Ms after the overlay starts.
      - `depth` 'front' | 'behind_presenter', required: Where the overlay sits relative to the presenter: the person in the clip's camera recording, or in its uploaded footage when the clip has no camera. `front` paints over everything. `behind_presenter` paints it behind the person but over everything else: in any layout the person is matted out of their footage and redrawn above the overlay. Fullscreen and framed layouts keep the recorded room around them; a cut-out layout replaces the room with the clip background. New overlays start on `front`. Without a presenter the overlay paints in front either way.
    - `dimensions` OverlayDimensionsOutput, required: Overlay size in artboard pixels. Absolute (not a percentage) so the overlay shape never distorts when the artboard dimensions change. Both sides must be greater than 0 — the renderer lays the overlay out into this box, so a zero or negative side has no valid meaning.
      - `height` number, required
      - `width` number, required
    - `durationMs` number, required
    - `fontFamily` string, required: The overlay's font family. Normally one of the catalog families accepted on write, or a library font's family when `fontId` is set. Overlays created before that catalog can report another bundled family, such as `Graphik`.
    - `fontId` string: The library font the overlay renders with (a `font` item's id), absent for a catalog family.
    - `fontSize` number, required: Font size in artboard pixels — absolute, like `dimensions`, so text keeps its size relative to the frame. Renderers scale it by their render scale factor.
    - `fontWeight` number, required: Variable-font weight axis — 100 (thin) to 900 (black).
    - `fontWidth` number, required: Variable-font width axis, as a percentage — 100 is normal, 50 ultra-condensed, 150 extra-expanded.
    - `id` string, required: Text overlay ID
    - `letterSpacing` number, required: Tracking: space between letters, as a fraction of the font size (-0.05 at an 80px font pulls letters 4px closer; 0.1 spreads them 8px apart). Negative tightens; 0 is the font's own spacing.
    - `outline` string, nullable, required: Color of the outline (stroke) drawn around the letters, or null for no outline.
    - `point` OverlayPointOutput, required: Top-left corner of the overlay, as a percentage of the video canvas (0-100). Relative so the anchor survives video aspect ratio changes.
      - `xPct` number, required
      - `yPct` number, required
    - `shadow` 'none' | 'subtle' | 'deep', required: Drop shadow, matching the editor's Shadow menu. It falls from the background box when the text has one, else from the letters.
    - `startTimeMs` number, required: Start time. Milliseconds on the clip playback timeline (with cuts applied) — the same timeline as the cut transcript.
    - `text` string, required
    - `textAlign` 'left' | 'center' | 'right', required: Horizontal alignment of the text inside its overlay box.
    - `transition` 'smooth' | 'hard_cut', required: How one thing gives way to the next: `smooth` eases across the change, `hard_cut` swaps instantly.
    - `zIndex` integer, required: Stacking position among the clip's image, video and text overlays: 0 is the backmost. `depth` applies first — a `behind_presenter` overlay stays behind the presenter whatever its zIndex — so the order only matters among overlays at the same depth. Lottie overlays share the stack but aren't listed, so listed values can skip a number.

## 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-11-07** `0cc3fcd307ad`: 1 info
  - added the required property `textOverlays/items/letterSpacing` to the response with the `200` status
- **2026-10-30** `0b2b8234a7db`: 1 info
  - added the required property `textOverlays/items/backgroundPadding` to the response with the `200` status
- **2026-10-22** `156b28c30e54`: 1 info
  - added the optional property `textOverlays/items/depthChanges` to the response with the `200` status
- **2026-10-09** `9773130bbc2b`: 1 info
  - added the required property `textOverlays/items/animation` to the response with the `200` status
- **2026-10-08** `574947531a33`: 1 info
  - added the optional property `textOverlays/items/fontId` to the response with the `200` status

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