# Retrieve Videos

> Part of the [SpatialGen API documentation](/index.md). [HTML version of this page](/api/00_retrieve_videos/).

Fetch videos and their ready streams from your SpatialGen workspace

## API context

-   API requests use `https://spatialgen.com` with the `/api` path prefix, included once.
-   Authenticate requests to SpatialGen API endpoints with the `X-SPATIALGEN-APPKEY` HTTP header.
-   Use a key from the workspace that owns the requested resources. Follow the roles and scopes specified for each endpoint below.
-   Keep `admin` and `upload` keys on a trusted backend. `readonly` keys may be used in client apps for permitted read operations.
-   Presigned upload URLs have their own authorization. Do not send your SpatialGen API key to those URLs.

See the [API key guide](/guides/get-started.md) for roles, key creation, expiration, revocation, and rotation.

* * *

**GET** `/api/videos`

Retrieves videos in the API key’s workspace, together with each video’s ready streams.

A video is included when it is not deleted, has a thumbnail, and has at least one stream job with a stream URL. Published and unpublished videos are both included. Deleted videos, videos without a thumbnail, and videos without a stream job URL are omitted.

Each video’s `streams` array contains every stream that is `ready`, not deleted, and belongs to the same workspace. When you do not pass `visibility`, a video can be returned with an empty `streams` array if it has a stream job but no ready stream. When you do pass `visibility`, videos with no matching streams are omitted.

Results follow library order: Home first, then other folders by folder id, and within each folder by position.

To list only published videos and the single most recent stream for each one, use [Retrieve Published Videos](/api/01_published_videos/).

Allowed API Key Roles

`admin`, `readonly`

### Query Parameters

| Parameter | Type | Required | Description |
| :-- | :-- | :-- | :-- |
| `folderName` | `string` | No | Filters results by folder name. Repeat this parameter to include videos from several folders. `Home` selects videos that are not in a folder. Names are matched exactly and are case-sensitive. Blank values are ignored. If omitted, videos from every folder are returned. |
| `visibility` | `string` | No | Filters streams by visibility. Accepted values are `public` and `drm`. Repeat this parameter to include more than one visibility. If omitted, every ready stream is returned. |

Any other query parameter is rejected.

### Example request

getVideos.js

```js
fetch('https://spatialgen.com/api/videos', {
    method: 'GET',
    headers: {
        'X-SPATIALGEN-APPKEY': apiKey,
    }
})
```

### Example request filtered by folder and visibility

getVideosFiltered.js

```js
fetch('https://spatialgen.com/api/videos?folderName=Launch%20Assets&folderName=Home&visibility=drm', {
    method: 'GET',
    headers: {
        'X-SPATIALGEN-APPKEY': apiKey,
    }
})
```

### Example Response

response.json

```json
[
    {
        "streams": [
            {
                "createdAt": string,              // Date in string format
                "status": string,                 // Always "ready"
                "streamName": string,             // Name of the stream
                "streamUrl": string,              // URL for the stream
                "visibility": string,             // "public" or "drm"
                "highestResolutionURL": string,   // URL to the highest resolution converted video
                "highestResolutionBytes": number, // Bytes in the highest resolution converted video
                "jobId": number                   // Stream job ID, or -1 when no job matches this stream URL
            }
        ],
        "library": {
            "createdAt": string,            // Date in string format
            "description": string,          // Description of the video
            "fileFormat3D": string,         // Format of the 3D file
            "folderName": string,           // Folder name, or "Home" when the video is not in a folder
            "id": number,                   // ID of the video
            "is3D": boolean,                // If the video is in 3D
            "isStreaming": boolean,         // If the video is streaming
            "perspective": number,          // Perspective
            "thumbnailUrl": string,         // Thumbnail URL
            "videoLength": number,          // Length of the video in seconds
            "videoHeight": number,          // Height of the video
            "videoName": string             // Name of the video
        }
    }
]
```

### Errors

Error bodies use `{ "status": <code>, "error": "<message>" }`. An empty match is `404`, not an empty array.

-   **400** — The `X-SPATIALGEN-APPKEY` header is missing. `Invalid request: missing X-SPATIALGEN-APPKEY header`
-   **400** — `visibility` is not `public` or `drm`. `Invalid request: visibility must be either public or drm`
-   **400** — The query includes a parameter this endpoint does not accept. `Invalid request: …`
-   **401** — The API key is revoked, expired, or not recognized. `Invalid API key`
-   **403** — The API key does not include the `videos:read` scope. `upload` keys do not include this scope. `API key missing required scope: videos:read`
-   **404** — `folderName` was set, none of those folders exist in the workspace, and `Home` was not requested. `No videos found in the specified folders`
-   **404** — The workspace has no videos that match the filters. `No published videos found for this workspace and filter set`
-   **405** — The request method is not `GET`. `Method Not Allowed`