---
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://edgetunnel-b2h.pages.dev/changelog-preview.png
---

> Documentation Index  
> Fetch the complete documentation index at: https://edgetunnel-b2h.pages.dev/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://edgetunnel-b2h.pages.dev/changelog/rss/index.xml) [ View RSS feeds ](https://edgetunnel-b2h.pages.dev/fundamentals/new-features/available-rss-feeds/) 

![hero image](https://edgetunnel-b2h.pages.dev/_astro/hero.CVYJHPAd_26AMqX.svg) 

[ ← Back to all posts ](https://edgetunnel-b2h.pages.dev/changelog/) 

## Custom metadata filtering for AI Search

Mar 23, 2026 

[ AI Search ](https://edgetunnel-b2h.pages.dev/ai-search/) 

[AI Search](https://edgetunnel-b2h.pages.dev/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`):

```bash
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://edgetunnel-b2h.pages.dev/ai-search/configuration/data-source/r2/#custom-metadata) for examples.
* **Website**: Add `<meta>` tags to your HTML pages. Refer to [Website custom metadata](https://edgetunnel-b2h.pages.dev/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`:

```bash
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://edgetunnel-b2h.pages.dev/ai-search/configuration/indexing/metadata/).

```json
{"@context":"https://schema.org","@type":"BlogPosting","@id":"https://edgetunnel-b2h.pages.dev/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://edgetunnel-b2h.pages.dev/changelog/post/2026-03-23-custom-metadata-filtering/","inLanguage":"en","image":"https://edgetunnel-b2h.pages.dev/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://edgetunnel-b2h.pages.dev/#website","name":"Cloudflare Docs","url":"https://edgetunnel-b2h.pages.dev/"}}
```