> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Metadata

> Add technical, contextual, and user-defined metadata to your videos.

> **Note**
>
> This guide covers adding user-defined metadata to already-indexed videos using the [Partial update video information](/v1.3/api-reference/videos/update) method. You can also provide user-defined metadata when uploading content using the [Create an asset](/v1.3/api-reference/upload-content/direct-uploads/create) method.

Metadata includes technical and contextual information about each video uploaded to the platform. User-defined metadata allows you to add more data to your videos, providing more detailed, specialized, or context-specific information.

Each value you provide is a string, a number, a boolean, or an array of strings. The platform stores each value with the type you send. It rejects a nested object and an array that contains anything but strings.

# Provide user-defined metadata

Once the platform has finished indexing your videos, you can provide user-defined metadata by invoking the `update` method of the `indexes.videos` object with the following parameters:

* `index_id`:  A string representing the unique identifier of the index containing the video for which you want to provide user-defined metadata.
* `video_id`:  A string representing the unique identifier of the video
* `user_metadata`: A dictionary containing your user-defined metadata.  In this example, the `metadata` dictionary has four keys: `views`, `downloads`, `language` and `country`. The `views` and `downloads` keys are integers, and the`creation_date` and `country` keys  are strings.

**`Python`**

```python Python
from twelvelabs import TwelveLabs

client.indexes.videos.update(
    index_id="<YOUR_INDEX_ID>",
    video_id="<YOUR_VIDEO_ID>",
    user_metadata={
        "views": 12000,
        "downloads": 40000,
        "language": "en-us",
        "country": "USA"
    }
)
```

**`Node.js`**

```javascript Node.js
import { TwelveLabs } from "twelvelabs-js";

client.indexes.videos.update(
    "<YOUR_INDEX_ID>",
    "<YOUR_VIDEO_ID>",
    {
        userMetadata: {
            views: 12000,
            downloads: 40000,
            language: "en-us",
            country: "USA",
        },
    },
);
```

# Filter on user-defined metadata

Once you've added user-defined metadata to your videos, you can use it to filter your search results.

The example code below filters on a custom field named `views` of type `integer`. The platform will return only the results found in the videos for which the value of the `views` field equals `120000`.

**`Python`**

```python Python maxlines=12
from twelvelabs import TwelveLabs

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>",
  query_text= "<YOUR_QUERY>",
  search_options=["visual"],
  filter = "{ "views": 120000}"
)
```

**`Node.js`**

```javascript Node.js maxlines=12
import { TwelveLabs } from "twelvelabs-js";

const search_results = client.search.query({
    indexId: "<YOUR_INDEX_ID>",
    queryText: "<YOUR_QUERY>",
    searchOptions: ["visual"],
    filter: "{"views": 120000}",
})
```

For more details on filtering search results, see the [Filtering](/v1.3/docs/guides/search/filtering) page.