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

> Browse and filter your Private Video Library with pagination, status, and capture metadata filters.

<Info>
  **Product**: Visual Search
  **Use case**: Upload videos and images, auto-index them, then search by natural language, image, or transcript phrase
  **Host**: `https://api.memories.ai/serve/api/v1`
  **Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
</Info>

Browse and filter your Private Video Library. Returns a paginated list of uploaded videos with status, duration, file size, and any capture metadata.

## Prerequisites

* You have [created a memories.ai API key](/visual-search/create-your-key).
* You have uploaded at least one video using the [Upload API](/visual-search/upload-video-from-file) (metadata-based filters require the video to have finished parsing so that its summary/metadata row is populated).

## Endpoint

POST /serve/api/v1/list\_videos

## Authentication

Pass your API key in the `Authorization` request header. Requests without a valid API key are rejected.

```
Authorization: sk-mavi-...
```

## Request Example

<Note>Uses `application/json` — send the request body as JSON, not form data.</Note>

Basic listing:

```python theme={null}
import requests

headers = {"Authorization": "sk-mavi-..."}
json_body = {
    "page": 1,
    "size": 200,
    "folder_id": 671631448308117504
}
response = requests.post(
    "https://api.memories.ai/serve/api/v1/list_videos",
    headers=headers,
    json=json_body
)
print(response.json())
```

Listing filtered by capture metadata (GPS radius + camera + tag + minimum capture time):

```python theme={null}
json_body = {
    "page": 1,
    "size": 50,
    # --- metadata filters ---
    "camera_model": "Canon EOS 5D",
    "tag": "holiday",
    "datetime_taken": 1729388400000,  # ms since epoch; only videos captured at/after this time
    "latitude": 39.9042,
    "longitude": 116.4074,             # latitude + longitude must be supplied together (≈20 km radius)
    # --- optional: restrict to a specific set of video_nos ---
    "video_nos": ["VI606404158946574336", "VI606402870447996928"]
}
```

## Request Parameters

### Basic filters

<ParamField body="page" type="integer" default="1">
  One-based page number. Must be **> 0**.
</ParamField>

<ParamField body="size" type="integer" default="200">
  Number of items per page. Must be **> 0**.
</ParamField>

<ParamField body="folder_id" type="integer">
  Optional. Restrict results to a single folder. Omit to query across your entire account. `-1` is the Default folder. Must be a folder that belongs to your account.
</ParamField>

<ParamField body="video_name" type="string">
  Exact-match filter on the stored video name.
</ParamField>

<ParamField body="video_no" type="string">
  Exact-match filter on a single video identifier.
</ParamField>

<ParamField body="video_nos" type="array">
  Restrict results to a specific set of video identifiers. Combined via `AND` with any other filter. When used alongside metadata filters, the final result is the **intersection** of the two sets.
</ParamField>

<ParamField body="status" type="string">
  Filter by processing status. One of `PARSE`, `UNPARSE`, `FAIL`. Note that the server rejects the legacy `FAILED` spelling with a JSON parse error referencing the live enum (`[UNPARSE, PARSE, FAIL]`).
</ParamField>

### Metadata filters

All metadata filters are resolved against the `summary` table that the upload pipeline populates after a video finishes parsing. A video whose summary is not yet available will not appear in the result when any metadata filter is applied.

<ParamField body="camera_model" type="string">
  Exact-match filter on the `camera_model` supplied at upload time.
</ParamField>

<ParamField body="tag" type="string">
  Single tag filter — the video's tag array must contain this value. To filter by multiple tags, issue separate requests and intersect client-side (server applies AND-with-other-filters semantics).
</ParamField>

<ParamField body="datetime_taken" type="integer">
  Minimum capture timestamp in **milliseconds since epoch**. Videos whose `capture_timestamp >= datetime_taken` are returned.
</ParamField>

<ParamField body="latitude" type="number">
  Decimal latitude. **Must be supplied together with `longitude`**; supplying only one returns *"The latitude and longitude parameters must be provided together."*
</ParamField>

<ParamField body="longitude" type="number">
  Decimal longitude. **Must be supplied together with `latitude`**. The server applies a \~20 km radius geo-within filter around the point.
</ParamField>

## Notes & Limits

* **Rate limiting**: The endpoint is protected by a per-account rate limit. Exceeding the limit returns an error indicating the request has exceeded the limit.
* **Metadata-filter resolution**: When any of `camera_model`, `tag`, `datetime_taken`, `latitude`+`longitude` is supplied, the server first queries the summary table, then restricts the listing to matching videos. If nothing matches, an empty page is returned (the request still succeeds).
* **Legacy compatibility**: Requests that only use the basic filters (`page / size / video_name / video_no / status`) behave exactly as before; response adds the new metadata fields only for videos that have them.

## Response Example

<Note>Numeric fields (`duration`, `size`, `create_time`, `total_count`, `datetime_taken`) are returned as **strings**, even though they represent integers — convert with `int(...)` before doing arithmetic.</Note>

```json theme={null}
{
    "code": "0000",
    "msg": "success",
    "data": {
        "current_page": 1,
        "page_size": 20,
        "total_count": "2",
        "videos": [
            {
                "video_no": "VI702915390254350336",
                "video_name": "NkdWNOrQByo",
                "duration": "105",
                "size": "7798243",
                "status": "PARSE",
                "cause": "null",
                "create_time": "1777047288621",
                "video_url": "https://mavi-resource.openinterx.com/VI9aa17ce1-f278-42b0-aff8-9f7ae3a70775.mp4",
                "cover_url": "https://mavi-resource.openinterx.com//VI9aa17ce1-f278-42b0-aff8-9f7ae3a70775/frame_0032.jpg",
                "fps": null,
                "width": null,
                "height": null,
                "resolution_label": null,
                "tags": ["living_room", "couch", "cat", "kitchen", "pov_laundry", "api"],
                "bucket": "mavi-resource",
                "blob": "VI9aa17ce1-f278-42b0-aff8-9f7ae3a70775.mp4"
            }
        ]
    },
    "success": true,
    "failed": false
}
```

## Response Fields

<ResponseField name="code" type="string">
  Business status code. `0000` indicates success.
</ResponseField>

<ResponseField name="msg" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.current_page" type="integer">
  Echo of the requested page number (one-based).
</ResponseField>

<ResponseField name="data.page_size" type="integer">
  Echo of the requested page size.
</ResponseField>

<ResponseField name="data.total_count" type="string">
  Total number of matching videos across all pages, returned as a string.
</ResponseField>

<ResponseField name="data.videos" type="array">
  Page of matching videos. Each item carries the basic video fields plus — when available — the capture-time metadata supplied at upload.
</ResponseField>

### Video item fields

<ResponseField name="video_no" type="string">
  Unique video identifier.
</ResponseField>

<ResponseField name="video_name" type="string">
  Internal stored name of the video.
</ResponseField>

<ResponseField name="duration" type="string">
  Video duration in seconds, returned as a string (`int(duration)` to use it).
</ResponseField>

<ResponseField name="size" type="string">
  Video file size in bytes, returned as a string.
</ResponseField>

<ResponseField name="create_time" type="string">
  Upload time in milliseconds since epoch, returned as a string.
</ResponseField>

<ResponseField name="status" type="string">
  Processing status. One of:

  * `PARSE` — ready for chat/search.
  * `UNPARSE` — uploaded but not yet fully processed.
  * `FAIL` — processing failed (see `cause`).
</ResponseField>

<ResponseField name="cause" type="string">
  Failure reason. Always present; carries the literal string `"null"` when there is no failure.
</ResponseField>

<ResponseField name="video_url" type="string">
  Hosted CDN URL of the original video on `mavi-resource.openinterx.com`. Suitable as a `file_uri` for [Gemini VLM](/visual-intelligence/gemini/gemini-vlm) without re-uploading.
</ResponseField>

<ResponseField name="cover_url" type="string">
  Hosted CDN URL of the auto-extracted cover frame (typically frame 32). Useful as a thumbnail in listing UIs.
</ResponseField>

<ResponseField name="fps" type="number">
  Frame rate of the source video. May be `null` for older uploads.
</ResponseField>

<ResponseField name="width" type="integer">
  Pixel width of the source video. May be `null` for older uploads.
</ResponseField>

<ResponseField name="height" type="integer">
  Pixel height of the source video. May be `null` for older uploads.
</ResponseField>

<ResponseField name="resolution_label" type="string">
  Human-readable resolution label (e.g. `720p`). May be `null` for older uploads.
</ResponseField>

### Metadata fields

These fields are only present when the corresponding value was supplied at upload time **and** the video's summary row has been written.

<ResponseField name="datetime_taken" type="string">
  Capture timestamp in milliseconds since epoch, returned as a string.
</ResponseField>

<ResponseField name="camera_model" type="string">
  Camera/device model recorded at upload.
</ResponseField>

<ResponseField name="latitude" type="number">
  Decimal latitude.
</ResponseField>

<ResponseField name="longitude" type="number">
  Decimal longitude.
</ResponseField>

<ResponseField name="tags" type="array">
  Combined tag set: the user-supplied tags from upload time **plus** scene/object tags auto-generated by the indexing pipeline (e.g. `living_room`, `couch`, `cat`). The server also appends an `api` tag on every API upload. There is no way to distinguish user vs auto tags in the response.
</ResponseField>

### Storage fields

<ResponseField name="bucket" type="string">
  GCS bucket of the original video file. Omitted when the storage location cannot be resolved.
</ResponseField>

<ResponseField name="blob" type="string">
  GCS blob (object) path of the video file. Use it with `bucket` at `GET /serve/api/v2/download?bucket=&blob=` to fetch the file directly.
</ResponseField>


## OpenAPI

````yaml POST /serve/api/v1/list_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/list_videos:
    post:
      summary: List Videos
      operationId: list_videos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListVideosRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVideosResponse'
components:
  schemas:
    ListVideosRequest:
      type: object
      properties:
        page:
          type: integer
          default: 1
          minimum: 1
          description: One-based page number. Must be > 0.
        size:
          type: integer
          default: 200
          minimum: 1
          description: Items per page. Must be > 0.
        video_name:
          type: string
          description: Exact-match filter on the stored video name.
        video_no:
          type: string
          description: Exact-match filter on a single video identifier.
        video_nos:
          type: array
          items:
            type: string
          description: >-
            Restrict results to a specific set of video identifiers. Combined
            via AND with other filters; intersected with the metadata-filter
            result when both are used.
          example:
            - VI606404158946574336
            - VI606402870447996928
        status:
          type: string
          enum:
            - PARSE
            - UNPARSE
            - FAILED
          description: Filter by processing status.
        camera_model:
          type: string
          example: Canon EOS 5D
          description: >-
            Metadata filter: exact-match on the camera_model supplied at upload
            time.
        tag:
          type: string
          example: holiday
          description: 'Metadata filter: single tag that must be present on the video.'
        datetime_taken:
          type: integer
          format: int64
          example: 1729388400000
          description: >-
            Metadata filter: minimum capture timestamp in milliseconds since
            epoch. Matches videos whose capture_timestamp >= this value.
        latitude:
          type: number
          format: double
          example: 39.9042
          description: >-
            Metadata filter: decimal latitude. Must be supplied together with
            longitude.
        longitude:
          type: number
          format: double
          example: 116.4074
          description: >-
            Metadata filter: decimal longitude. Must be supplied together with
            latitude. ~20 km geo-within radius.
        folder_id:
          type: integer
          description: >-
            Optional. Restrict results to a single folder. Omit to query across
            your entire account. -1 is the Default folder; a positive id must
            belong to your account.
          example: 671631448308117500
    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

````