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

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/changelog/llms.txt  
> Use this file to discover all available pages before exploring further. 

[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" }    ]  }'
```

#### 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 }        }      }    }  }'
```

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

```json
{"@context":"https://schema.org","@type":"BlogPosting","@id":"https://developers.cloudflare.com/changelog/post/2026-03-23-custom-metadata-filtering/#page","headline":"Custom metadata filtering for AI Search · Changelog","description":"Define custom metadata fields and filter search results by category, version, or any custom attribute.","url":"https://developers.cloudflare.com/changelog/post/2026-03-23-custom-metadata-filtering/","inLanguage":"en","image":"https://developers.cloudflare.com/changelog-preview.png","dateModified":"2026-03-23","datePublished":"2026-03-23","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```