---
title: "List Tella Motion documents"
method: GET
path: "/v1/motion/documents"
tags: ["Tella Motion"]
---

# List Tella Motion documents

`GET /v1/motion/documents`

## Request

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

Lists Tella Motion documents you can edit, newest first. With `storyId`, a video's: its Tella Motion clips' and the documents its overlays and b-roll play. Without it, your documents that no video plays yet. Every one plays live where the video uses it, so an edit shows in the video at once. Tella Motion media in the library is a frozen snapshot, which becomes a new document of the video's when placed.

## Query parameters

- `storyId` string: The video (vid_…) whose documents to list. Leave it out for your documents that no video plays yet.

## Response `200`

OK

- ListMotionDocumentsResponse: Tella Motion documents you can edit, newest first: the video's (its Tella Motion clips' and the documents its overlays and b-roll play), or without a video, yours that no video plays yet.
  - `documents` MotionDocument[], required
    - `createdAt` string, required
    - `id` string, required: Document ID
    - `name` string, required
    - `ownerID` string, required: The owner's ID: the video's, for `story` documents; yours, for `user` documents.
    - `sceneID` string: The clip that plays this document, when it is a Tella Motion clip's. Absent for overlays and b-roll.
    - `scope` string, required: Who owns the document: `story` for a video's own documents (its Tella Motion clips, overlays and b-roll), `user` for one of yours that no video plays yet.

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

> 65 revisions in range; 1 not diffed.

- **2026-10-27** `240a74ea0ff7`: 1 info
  - the `query` request parameter `storyId` became optional
- **2026-10-22** `156b28c30e54`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/motion/documents/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/0cc3fcd307ad?raw)