> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List Videos in Folder
> List the videos contained in a specific folder, with pagination.
**Product**: Visual Search
**Use case**: Organize your indexed videos into folders and scope uploads/searches to a folder
**Host**: `https://api.memories.ai/serve/api/v1`
**Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
List the videos inside a single folder, paginated. The response shape matches [List Videos](/visual-search/list-videos). To list across your entire account (all folders), use [List Videos](/visual-search/list-videos) instead — or pass its optional `folder_id`.
## Prerequisites
* You have [created a memories.ai API key](/visual-search/create-your-key).
* You have a folder id from [List Folders](/visual-search/list-folders).
## Request Example
```python theme={null}
import requests
headers = {"Authorization": "sk-mavi-..."}
params = {"folder_id": 671631448308117504, "page": 1, "page_size": 20}
response = requests.get(
"https://api.memories.ai/serve/api/v1/folders/videos",
headers=headers,
params=params,
)
print(response.json())
```
```bash cURL theme={null}
curl --get "https://api.memories.ai/serve/api/v1/folders/videos" \
-H "Authorization: sk-mavi-..." \
--data-urlencode "folder_id=671631448308117504" \
--data-urlencode "page=1" \
--data-urlencode "page_size=20"
```
## Parameters
Folder to list. `-1` is the Default folder, `-2` the legacy API folder. Any other value must be a folder that belongs to your account.
One-based page number. Must be **> 0**.
Number of items per page. Must be **> 0**.
## Response Example
```json theme={null}
{
"code": "0000",
"msg": "success",
"data": {
"current_page": 1,
"page_size": 20,
"total_count": 35,
"videos": [
{
"video_no": "VI671631448308117504",
"video_name": "demo",
"duration": 12345,
"size": 1048576,
"create_time": 1751856000000,
"status": "PARSE",
"video_url": "https://...",
"cover_url": "https://..."
}
]
}
}
```
## Response Fields
Business status code. `0000` indicates success.
Human-readable status message.
The page number returned (one-based).
Items per page.
Total number of videos in the folder.
Videos in this page. Each item has the same shape as [List Videos](/visual-search/list-videos) (`video_no`, `video_name`, `duration`, `size`, `create_time`, `status`, `video_url`, `cover_url`, and any capture metadata).
## Notes & Limits
* A folder that does not belong to your account returns `Folder does not exist or does not belong to the current user`.
* **Rate limiting**: Folder endpoints share a per-account rate limit. See [Rate limits](/visual-search/rate-limits).
## OpenAPI
````yaml GET /serve/api/v1/folders/videos
openapi: 3.1.0
info:
title: Memories Platform API (Docs Mapping)
version: v1
description: OpenAPI mapping used by Mintlify Try it for the platform docs.
servers:
- url: https://api.memories.ai
security:
- ApiKeyAuth: []
paths:
/serve/api/v1/folders/videos:
get:
summary: List Videos in Folder
operationId: list_folder_videos
parameters:
- name: folder_id
in: query
required: true
schema:
type: integer
example: 671631448308117500
description: >-
Folder to list. -1 Default folder, -2 legacy API folder, or a folder
that belongs to your account.
- name: page
in: query
schema:
type: integer
default: 1
description: One-based page number.
- name: page_size
in: query
schema:
type: integer
default: 20
description: Items per page.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListVideosResponse'
components:
schemas:
ListVideosResponse:
type: object
properties:
code:
type: string
example: '0000'
msg:
type: string
example: success
data:
type: object
properties:
current_page:
type: integer
example: 1
page_size:
type: integer
example: 20
total_count:
type: integer
format: int64
example: 2
videos:
type: array
items:
type: object
properties:
video_no:
type: string
example: VI606404158946574336
video_name:
type: string
example: 182082-867762198_tiny
duration:
type: integer
format: int64
example: 12
description: Video duration in seconds.
size:
type: integer
format: int64
example: 3284512
description: File size in bytes.
create_time:
type: integer
format: int64
example: 1754037217992
description: Upload time in ms since epoch.
status:
type: string
enum:
- PARSE
- UNPARSE
- FAILED
example: PARSE
cause:
type: string
description: Failure reason — only present when status=FAILED.
video_url:
type: string
description: Download URL — only present when available.
datetime_taken:
type: integer
format: int64
example: 1729388400000
description: >-
Capture timestamp (ms since epoch). Only present when
available.
camera_model:
type: string
example: Canon EOS 5D
description: Camera/device model. Only present when available.
latitude:
type: number
format: double
example: 39.9042
description: Decimal latitude. Only present when available.
longitude:
type: number
format: double
example: 116.4074
description: Decimal longitude. Only present when available.
tags:
type: array
items:
type: string
example:
- holiday
- beijing
- api
description: User-defined tags. Only present when non-empty.
bucket:
type: string
description: >-
GCS bucket of the original video file. Omitted when the
storage location cannot be resolved.
blob:
type: string
description: >-
GCS blob path of the video file. Use with bucket at GET
/serve/api/v2/download to fetch the file directly.
success:
type: boolean
example: true
failed:
type: boolean
example: false
example:
code: '0000'
msg: success
data:
current_page: 1
page_size: 20
total_count: 2
videos:
- video_no: VI606404158946574336
video_name: 182082-867762198_tiny
duration: 12
size: 3284512
status: PARSE
create_time: 1754037217992
datetime_taken: 1729388400000
camera_model: Canon EOS 5D
latitude: 39.9042
longitude: 116.4074
tags:
- holiday
- beijing
- api
bucket: mavi-resource
blob: VI606404158946574336.mp4
- video_no: VI606402870447996928
video_name: test_video_gz_visual_understanding_s36
duration: 61
size: 5324808
status: PARSE
create_time: 1754036910783
bucket: mavi-resource
blob: VI606402870447996928.mp4
success: true
failed: false
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````