---
title: "List Videos"
method: POST
path: "/serve/api/v1/list_videos"
---

# List Videos

`POST /serve/api/v1/list_videos`

## Request body

- ListVideosRequest
  - `page` integer — One-based page number. Must be > 0.
  - `size` integer — Items per page. Must be > 0.
  - `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.
  - `status` 'PARSE' | 'UNPARSE' | 'FAILED' — Filter by processing status.
  - `camera_model` string — Metadata filter: exact-match on the camera_model supplied at upload time.
  - `tag` string — Metadata filter: single tag that must be present on the video.
  - `datetime_taken` integer — Metadata filter: minimum capture timestamp in milliseconds since epoch. Matches videos whose capture_timestamp >= this value.
  - `latitude` number, double — Metadata filter: decimal latitude. Must be supplied together with longitude.
  - `longitude` number, double — Metadata filter: decimal longitude. Must be supplied together with latitude. ~20 km geo-within radius.
  - `folder_id` integer — 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.

## Response `200`

Successful response

- ListVideosResponse
  - `code` string
  - `msg` string
  - `data` object
    - `current_page` integer
    - `page_size` integer
    - `total_count` integer
    - `videos` object[]
      - `video_no` string
      - `video_name` string
      - `duration` integer — Video duration in seconds.
      - `size` integer — File size in bytes.
      - `create_time` integer — Upload time in ms since epoch.
      - `status` 'PARSE' | 'UNPARSE' | 'FAILED'
      - `cause` string — Failure reason — only present when status=FAILED.
      - `video_url` string — Download URL — only present when available.
      - `datetime_taken` integer — Capture timestamp (ms since epoch). Only present when available.
      - `camera_model` string — Camera/device model. Only present when available.
      - `latitude` number, double — Decimal latitude. Only present when available.
      - `longitude` number, double — Decimal longitude. Only present when available.
      - `tags` string[] — User-defined tags. Only present when non-empty.
      - `bucket` string — GCS bucket of the original video file. Omitted when the storage location cannot be resolved.
      - `blob` string — GCS blob path of the video file. Use with bucket at GET /serve/api/v2/download to fetch the file directly.
  - `success` boolean
  - `failed` boolean

---

[API](https://skmtc.dev/memories/apis/screenplay-extraction-api.md) · [All operations](https://skmtc.dev/memories/apis/screenplay-extraction-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/memories/screenplay-extraction-api/revisions/720c8c144ddc/schema)