List Videos

Prerequisites

You’re familiar with the concepts described on the Platform overview.
You have created a memories.ai API key.
You have uploaded at least one video using the Upload API (metadata-based filters require the video to have finished parsing so that its summary/metadata row is populated).

Host URL

https://api.memories.ai

https://api.memories.ai

Endpoint

POST /serve/api/v1/list_videos

/serve/api/v1/list_videos

Authentication

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

Authorization: <API_KEY>

Content Type

The endpoint expects a JSON body (application/json).

Request Example

Basic listing:

import requests

headers = {"Authorization": "<API_KEY>"}
json_body = {
    "page": 1,
    "size": 200,
    "unique_id": "default"
}
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):

json_body = {
    "page": 1,
    "size": 50,
    "unique_id": "default",
    # --- 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

page

integer

default:"1"

One-based page number. Must be > 0.

size

integer

default:"200"

Number of items per page. Must be > 0.

unique_id

string

default:"default"

Scope identifier for the authenticated account (corresponds to the upload-time unique_id). Must be non-empty. If the folder for this unique_id does not exist yet, it is created automatically.

video_name

string

Exact-match filter on the stored video name.

video_no

string

Exact-match filter on a single video identifier.

video_nos

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.

status

string

Filter by processing status. One of PARSE, UNPARSE, FAILED.

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.

camera_model

string

Exact-match filter on the camera_model supplied at upload time.

tag

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).

datetime_taken

integer

Minimum capture timestamp in milliseconds since epoch. Videos whose capture_timestamp >= datetime_taken are returned.

latitude

number

Decimal latitude. Must be supplied together with longitude; supplying only one returns “The latitude and longitude parameters must be provided together.”

longitude

number

Decimal longitude. Must be supplied together with latitude. The server applies a ~20 km radius geo-within filter around the point.

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 / unique_id / video_name / video_no / status) behave exactly as before; response adds the new metadata fields only for videos that have them.

Response 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"]
            },
            {
                "video_no": "VI606402870447996928",
                "video_name": "test_video_gz_visual_understanding_s36",
                "duration": 61,
                "size": 5324808,
                "status": "PARSE",
                "create_time": 1754036910783
            }
        ]
    },
    "success": true,
    "failed": false
}

Response Fields

code

string

Business status code. 0000 indicates success.

msg

string

Human-readable status message.

data.current_page

integer

Echo of the requested page number (one-based).

data.page_size

integer

Echo of the requested page size.

data.total_count

integer

Total number of matching videos across all pages.

data.videos

array

Page of matching videos. Each item carries the basic video fields plus — when available — the capture-time metadata supplied at upload.

Video item fields

video_no

string

Unique video identifier.

video_name

string

Internal stored name of the video.

duration

integer

Video duration in seconds.

size

integer

Video file size in bytes.

create_time

integer

Upload time in milliseconds since epoch.

status

string

Processing status. One of:

PARSE — ready for chat/search.
UNPARSE — uploaded but not yet fully processed.
FAILED — processing failed (see cause).

cause

string

Failure reason — only present when status=FAILED.

video_url

string

Download URL — only present when available.

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.

datetime_taken

integer

Capture timestamp in milliseconds since epoch.

camera_model

string

Camera/device model recorded at upload.

latitude

number

Decimal latitude.

longitude

number

Decimal longitude.

Authorizations

Authorization

string

header

required

Body

application/json

page

integer

default:1

One-based page number. Must be > 0.

Required range: x >= 1

size

integer

default:200

Items per page. Must be > 0.

Required range: x >= 1

unique_id

string

default:default

Scope identifier for the authenticated account. Folder is auto-created on first use.

video_name

string

Exact-match filter on the stored video name.

video_no

string

Exact-match filter on a single video identifier.

video_nos

string[]

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

enum<string>

Filter by processing status.

Available options:

PARSE,

UNPARSE,

FAILED

camera_model

string

Metadata filter: exact-match on the camera_model supplied at upload time.

Example:

"Canon EOS 5D"

tag

string

Metadata filter: single tag that must be present on the video.

Example:

"holiday"

datetime_taken

integer<int64>

Metadata filter: minimum capture timestamp in milliseconds since epoch. Matches videos whose capture_timestamp >= this value.

Example:

1729388400000

latitude

number<double>

Metadata filter: decimal latitude. Must be supplied together with longitude.

Example:

39.9042

longitude

number<double>

Metadata filter: decimal longitude. Must be supplied together with latitude. ~20 km geo-within radius.

Example:

116.4074

Response

200 - application/json

Successful response

code

string

Example:

"0000"

msg

string

Example:

"success"

data

object

Show child attributes

success

boolean

Example:

true

failed

boolean

Example:

false

Get Started

Upload (Indexing)

Search

Chat Strategies

Caption & Understanding

Text Memory

Utils

Reference

Prerequisites

Host URL

Endpoint

Authentication

Content Type

Request Example

Request Parameters

Basic filters

Metadata filters

Notes & Limits

Response Example

Response Fields

Video item fields

Metadata fields

Authorizations

Body

Response

Get Started

Upload (Indexing)

Search

Chat Strategies

Caption & Understanding

Text Memory

Utils

Reference

Documentation Index

​Prerequisites

​Host URL

​Endpoint

​Authentication

​Content Type

​Request Example

​Request Parameters

​Basic filters

​Metadata filters

​Notes & Limits

​Response Example

​Response Fields

​Video item fields

​Metadata fields

Authorizations

Body

Response

Prerequisites

Host URL

Endpoint

Authentication

Content Type

Request Example

Request Parameters

Basic filters

Metadata filters

Notes & Limits

Response Example

Response Fields

Video item fields

Metadata fields