---
title: Custom metadata filtering for AI Search
description: Define custom metadata fields and filter search results by category, version, or any custom attribute.
image: https://developers.cloudflare.com/changelog-preview.png
---

[Skip to content](#%5Ftop) 

# Changelog

New updates and improvements at Cloudflare.

[ Subscribe to RSS ](https://developers.cloudflare.com/changelog/rss/index.xml) [ View RSS feeds ](https://developers.cloudflare.com/fundamentals/new-features/available-rss-feeds/) 

![hero image](https://developers.cloudflare.com/_astro/hero.CVYJHPAd_26AMqX.svg) 

[ ← Back to all posts ](https://developers.cloudflare.com/changelog/) 

## Custom metadata filtering for AI Search

Mar 23, 2026 

[ AI Search ](https://developers.cloudflare.com/ai-search/) 

[AI Search](https://developers.cloudflare.com/ai-search/) now supports custom metadata filtering, allowing you to define your own metadata fields and filter search results based on attributes like category, version, or any custom field you define.

#### Define a custom metadata schema

You can define up to 5 custom metadata fields per AI Search instance. Each field has a name and data type (`text`, `number`, or `boolean`):

Terminal window

```

curl -X POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer {API_TOKEN}" \

  -d '{

    "id": "my-instance",

    "type": "r2",

    "source": "my-bucket",

    "custom_metadata": [

      { "field_name": "category", "data_type": "text" },

      { "field_name": "version", "data_type": "number" },

      { "field_name": "is_public", "data_type": "boolean" }

    ]

  }'


```

Explain Code

#### Add metadata to your documents

How you attach metadata depends on your data source:

* **R2 bucket**: Set metadata using S3-compatible custom headers (`x-amz-meta-*`) when uploading objects. Refer to [R2 custom metadata](https://developers.cloudflare.com/ai-search/configuration/data-source/r2/#custom-metadata) for examples.
* **Website**: Add `<meta>` tags to your HTML pages. Refer to [Website custom metadata](https://developers.cloudflare.com/ai-search/configuration/data-source/website/#custom-metadata) for details.

#### Filter search results

Use custom metadata fields in your search queries alongside built-in attributes like `folder` and `timestamp`:

Terminal window

```

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances/{NAME}/search \

  -H "Content-Type: application/json" \

  -H "Authorization: Bearer {API_TOKEN}" \

  -d '{

    "messages": [

      {

        "content": "How do I configure authentication?",

        "role": "user"

      }

    ],

    "ai_search_options": {

      "retrieval": {

        "filters": {

          "category": "documentation",

          "version": { "$gte": 2.0 }

        }

      }

    }

  }'


```

Explain Code

Learn more in the [metadata filtering documentation](https://developers.cloudflare.com/ai-search/configuration/indexing/metadata/).