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

# Get Video Metadata

> Fetch the full metadata record for a single video in your Private Video Library.

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

Fetch the full metadata record for a single video in your Private Video Library — status, duration, resolution, GPS, camera model, and tags.

This is also the canonical way to **poll indexing status** after [Upload Video](/visual-search/upload-video-from-file) or [Upload Image](/visual-search/upload-image-from-file) — read `data.status` and wait for it to become `PARSE`.

## Prerequisites

* You have [created a memories.ai API key](/visual-search/create-your-key).
* You have uploaded the target video using the [Upload API](/visual-search/upload-video-from-file) (metadata fields only become available after the video finishes parsing and its summary row is populated).

## Endpoint

GET /serve/api/v1/get\_metadata

## Authentication

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

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

## Request Example

```python theme={null}
import requests

url = "https://api.memories.ai/serve/api/v1/get_metadata"
params = {
    "video_no": "VI606404158946574336"
}
headers = {"Authorization": "sk-mavi-..."}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

## Query Parameters

<ParamField query="video_no" type="string" required>
  The video identifier returned by the upload API (e.g. `VI606404158946574336`). Must be non-empty.
</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 availability**: The capture-time metadata fields (`datetime_taken / camera_model / latitude / longitude`) are only present when the corresponding value was supplied at upload **and** the video's summary row has been written (i.e. after parsing completes). Videos not yet parsed return the basic fields only.
* **Not found is not an error**: If the video does not exist (or does not belong to this account), the response is `code: "0000"`, `success: true`, `data: null` — check `data` for `None` explicitly rather than relying on the status code.
* **Numeric field types are inconsistent**: `duration`, `size`, and `create_time` are returned as **strings**; `fps`, `width`, `height` are returned as actual integers. Cast `duration`/`size`/`create_time` with `int(...)` before arithmetic.

## Response Example

```json theme={null}
{
    "code": "0000",
    "msg": "success",
    "data": {
        "video_no": "VI702915390254350336",
        "video_name": "NkdWNOrQByo",
        "duration": "105",
        "size": "7798243",
        "status": "PARSE",
        "create_time": "1777047288621",
        "resolution_label": "720p",
        "fps": 30,
        "width": 640,
        "height": 360,
        "tags": ["living_room", "couch", "cat", "kitchen", "pov_laundry", "api"],
        "bucket": "mavi-resource",
        "blob": "VI702915390254350336.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" type="object">
  The video item. `null` when the video is not found.
</ResponseField>

### Basic fields

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

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

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

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

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

<ResponseField name="data.status" type="string">
  Processing status. One of `PARSE`, `UNPARSE`, `FAIL`.
</ResponseField>

<ResponseField name="data.cause" type="string">
  Failure reason — only present when `status=FAIL`.
</ResponseField>

<ResponseField name="data.resolution_label" type="string">
  Human-readable resolution label (e.g. `720p`, `1080p`). Lower-case `p`.
</ResponseField>

<ResponseField name="data.fps" type="integer">
  Frames per second.
</ResponseField>

<ResponseField name="data.width" type="integer">
  Frame width in pixels.
</ResponseField>

<ResponseField name="data.height" type="integer">
  Frame height in pixels.
</ResponseField>

### Metadata fields

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

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

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

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

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

<ResponseField name="data.tags" type="array">
  Combined tag set: user-supplied tags from upload **plus** scene/object tags auto-generated by the indexing pipeline (e.g. `living_room`, `couch`, `cat`), plus the auto-appended `api` tag. Unlike `list_videos`, this endpoint **always returns `tags`** once the video has finished parsing, even if no user tags were supplied at upload — the auto tags alone are enough to populate it.
</ResponseField>

### Storage fields

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

<ResponseField name="data.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. Note: `video_url` and `cover_url` are deliberately not returned by this endpoint — use `bucket`/`blob` instead.
</ResponseField>


## OpenAPI

````yaml GET /serve/api/v1/get_metadata
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/get_metadata:
    get:
      summary: Get Video Metadata
      operationId: get_video_metadata
      parameters:
        - name: video_no
          in: query
          required: true
          schema:
            type: string
          example: VI606404158946574336
          description: Video identifier. Must be non-empty.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMetadataResponse'
components:
  schemas:
    GetMetadataResponse:
      type: object
      properties:
        code:
          type: string
          example: '0000'
        msg:
          type: string
          example: success
        data:
          type: object
          nullable: true
          properties:
            video_no:
              type: string
              example: VI606404158946574336
            video_name:
              type: string
              example: 182082-867762198_tiny
            duration:
              type: integer
              format: int64
              example: 12
              description: 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 (ms since epoch).
            status:
              type: string
              enum:
                - PARSE
                - UNPARSE
                - FAILED
              example: PARSE
            cause:
              type: string
              description: Only present when status=FAILED.
            resolution_label:
              type: string
              example: 720P
            fps:
              type: integer
              example: 30
            width:
              type: integer
              example: 1280
            height:
              type: integer
              example: 720
            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: Only present when available.
            latitude:
              type: number
              format: double
              example: 39.9042
              description: Only present when available.
            longitude:
              type: number
              format: double
              example: 116.4074
              description: Only present when available.
            tags:
              type: array
              items:
                type: string
              example:
                - holiday
                - beijing
                - api
              description: Only present when non-empty.
            bucket:
              type: string
              description: >-
                GCS bucket of the video file. Omitted when the storage location
                cannot be resolved.
            blob:
              type: string
              description: >-
                GCS blob path of the video. 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:
          video_no: VI606404158946574336
          video_name: 182082-867762198_tiny
          duration: 12
          size: 3284512
          status: PARSE
          create_time: 1754037217992
          resolution_label: 720P
          fps: 30
          width: 1280
          height: 720
          datetime_taken: 1729388400000
          camera_model: Canon EOS 5D
          latitude: 39.9042
          longitude: 116.4074
          tags:
            - holiday
            - beijing
            - api
          bucket: mavi-resource
          blob: VI606404158946574336.mp4
        success: true
        failed: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````