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

# Filtering

> Filter search results to find more specific content in videos.

When you perform a search, the platform returns all the relevant matches. Filtering narrows the scope of your query. The platform allows you to filter your search results based on metadata or the level of confidence that the search results match your query.

# Filtering search results based on metadata

To filter your search results based on metadata, use the `filter` parameter.

The `filter` parameter is of type `Object` and can contain both system-generated and user-provided metadata fields.fields. For details on system-generated metadata, see the [Video object](/v1.3/api-reference/videos/the-video-object) page. For details on providing custom metadata, see the [Update video information](/v1.3/api-reference/videos/update) page.

To indicate the relationship between a field and its value, you can use the exact match or comparison operators.

## Exact match operator

The exact match operator matches only the results that equal the value you specify. The syntax is as follows: `<field>: <value>`.

## Comparison operators

Use the comparison operators (`lte` and `gte`) to match based on the arithmetic comparison. The syntax is as follows: `<field>:{"gte": <value>, "lte": <value}`.

## Filter composition

You can filter on multiple fields by adding the fields you want to filter on to the `filter` parameter as shown in the [Filter on size, width, and height](/v1.3/docs/guides/search/filtering#filter-on-size-width-and-height) section below.

# Examples

## Filter on a specific video ID

The following example code uses the `id` field of the `filter` parameter to filter on a specific video ID:

**`Python`**

```python Python maxlines=12
search_pager = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query_text="<YOUR_QUERY>",
    search_options=["visual"],
    filter=json.dumps({"id":["<YOUR_VIDEO_ID>"]})
)
```

**`Node.js`**

```javascript Node.js maxlines=12
let searchPager = await client.search.query({
  indexId: "<YOUR_INDEX_ID>",
  queryText: "<YOUR_QUERY>",
  searchOptions: ["visual"],
  filter: JSON.stringify({ id: ["<YOUR_INDEX_ID>"] }),
});
```

## Filter on multiple video IDs

The following example code uses the `id` field of the `filter` query parameter to filter on multiple video IDs:

**`Python`**

```python Python maxlines=12
search_pager = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query_text="<YOUR_QUERY>",
    search_options=["visual"],
    filter=json.dumps({"id":["<FIRST_VIDEO_ID>", "<SECOND_VIDEO_ID>"]})
)
```

**`Node.js`**

```javascript Node.js maxlines=12
let searchPager = await client.search.query({
  indexId: "<YOUR_INDEX_ID>",
  queryText: "<YOUR_QUERY>",
  searchOptions: ["visual"],
  filter: JSON.stringify({ id: ["<FIRST_VIDEO_ID>","<SECOND_VIDEO_ID>"] }),
});
```

## Filter on size, width, and height

The example code below uses the `size`, `width`, and `height` fields of the `filter`  parameter to return only the matches found in videos that meet all the following criteria:

* Size is greater than or equal to `50000000` bytes and less and equal to `53000000` bytes.
* Width is greater than or equal to `850`.
* Height is greater than or equal to `400` and less and equal to `500.`

**`Python`**

```python Python maxlines=12
search_pager = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query_text="<YOUR_QUERY>",
    search_options=["visual"],
    filter=json.dumps({
        "size": {
            "gte": 50000000, "lte": 53000000
        },
        "width":
        {
            "gte": 850
        },
        "height":
        {
            "gte": 400, "lte": 500
        }
    })
)
```

**`Node.js`**

```javascript Node.js maxlines=12
let searchPager = await client.search.query({
  indexId: "<YOUR_INDEX_ID>",
  queryText: "<YOUR_QUERY>",
  searchOptions: ["visual"],
  filter: JSON.stringify(
      {
          size: {
              gte: 50000000,
              lte: 53000000,
          },
          width: {
              gte: 850,
          },
          height: {
              gte: 400,
              lte: 500,
          },
      }
  )
});
```

## Filter on custom metadata

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

**`Python`**

```python Python maxlines=12
search_pager = client.search.query(
    index_id="<YOUR_INDEX_ID>",
    query_text="<YOUR_QUERY>",
    search_options=["visual"],
    filter=json.dumps({"views":120000})
)
```

**`Node.js`**

```javascript Node.js maxlines=12
let searchPager = await client.search.query({
  indexId: "<YOUR_INDEX_ID>",
  queryText: "<YOUR_QUERY>",
  searchOptions: ["visual"],
  filter: JSON.stringify({ views: 120000 }),
});
```

> Filter search results to find more specific content in videos.