Filter Cookbook

Complete reference for the 12 filter types, per-index filterable fields, AI label taxonomy, and ready-to-use filter recipes.

For an overview of the Search endpoints and how filters fit into the Studio API pipeline, see the Search guide.

Base URL: https://api.mbd.xyz/v3/studio Auth: Authorization: Bearer <your-console-api-key> — get your key from the Embed Console

All YOUR_API_KEY placeholders in this guide refer to your console API key (starts with mbd-).

How Filters Work

Every search request (/search/filter_and_sort and /search/boost) accepts three filter arrays:

Combined logic: (include[0] AND include[1] AND ...) AND NOT (exclude[0] OR exclude[1] OR ...)

Each filter object always has filter (the type) and field. Other properties depend on the type.

Quick Reference: All 12 Filter Types

Filter Type Reference

term

Exact match on a keyword field. The field value must exactly equal the specified value.

Required: field, value (string or boolean)

{ "filter": "term", "field": "active", "value": true }

{ "filter": "term", "field": "lang", "value": "en" }

{ "filter": "term", "field": "featured", "value": true }

Use with: include (only active markets), exclude (remove closed markets), boost (boost featured items)

terms

Multiple values where at least one must match (OR logic within the filter). Useful for filtering by several categories, channels, or labels at once.

Required: field, value (array of strings)

{ "filter": "terms", "field": "ai_labels_med", "value": ["mbd2:t_science_technology", "mbd2:t_sports"] }

{ "filter": "terms", "field": "channels", "value": ["dev", "crypto", "ai"] }

{ "filter": "terms", "field": "lang", "value": ["en", "es", "fr"] }

Use with: include (match any of these labels), exclude (remove posts in any of these channels)

numeric

Range comparison on numeric fields. Supports >, >=, <, <= operators.

Required: field, operator, value (number)

{ "filter": "numeric", "field": "liquidity_num", "operator": ">", "value": 10000 }

{ "filter": "numeric", "field": "volume_24hr", "operator": ">=", "value": 50000 }

{ "filter": "numeric", "field": "user_score_spam", "operator": "<", "value": 0.5 }

Field name gotchas (Polymarket):

• Use liquidity_num not liquidity — liquidity can be null and will silently miss results.
• Use ai_labels_med not ai_labels — the field ai_labels does not exist.
• Use slug not market_slug — market_slug does not exist.

Tip: Combine two numeric filters on the same field to create a range:

[
  { "filter": "numeric", "field": "liquidity_num", "operator": ">=", "value": 5000 },
  { "filter": "numeric", "field": "liquidity_num", "operator": "<=", "value": 500000 }
]

match

Full-text search on text fields. Matches documents containing any of the specified keywords (analyzed, not exact).

Required: field, value (array of keywords)

{ "filter": "match", "field": "question", "value": ["election", "president"] }

{ "filter": "match", "field": "text", "value": ["bitcoin", "ethereum"] }

{ "filter": "match", "field": "zora_description", "value": ["art", "generative"] }

Difference from term/terms: match uses Elasticsearch's full-text analyzer (tokenization, stemming). Use term/terms for exact keyword-field matches; use match for natural-language text search.

date

Range filtering on date fields. Provide an object with date_from and/or date_to in ISO 8601 format.

Required: field, value (object with date_from and/or date_to)

{
  "filter": "date",
  "field": "end_date",
  "value": {
    "date_from": "2026-03-01T00:00:00Z",
    "date_to": "2026-06-30T23:59:59Z"
  }
}

{
  "filter": "date",
  "field": "item_creation_timestamp",
  "value": {
    "date_from": "2026-02-01T00:00:00Z"
  }
}

{
  "filter": "date",
  "field": "zora_created_at",
  "value": {
    "date_from": "2026-02-05T00:00:00Z",
    "date_to": "2026-02-12T23:59:59Z"
  }
}

Date fields by index:

• polymarket-items: created_at, updated_at, end_date, start_date, game_start_time
• polymarket-wallets: updated_at
• farcaster-items: item_creation_timestamp
• zora-coins: zora_created_at, zora_updated_at

geo

Geographic distance filtering on geo-point fields. Values use the geo:lat,lon string format.

Required: field, value (array of "geo:lat,lon" strings)

{ "filter": "geo", "field": "location", "value": ["geo:40.7128,-74.0060"] }

Applicable index: farcaster-items (field: location)

is_null

Finds documents where the specified field is null or missing. No value needed.

Required: field

{ "filter": "is_null", "field": "zora_creator_farcaster_id" }

{ "filter": "is_null", "field": "zora_media_content_type" }

Use with: include (find items without a field), exclude (remove items missing a field — equivalent to not_null in include)

not_null

Finds documents where the specified field exists and has a value. No value needed.

Required: field

{ "filter": "not_null", "field": "user_id" }

{ "filter": "not_null", "field": "zora_creator_farcaster_id" }

custom

Pass a raw Elasticsearch query clause for advanced use cases not covered by other filter types. The field property is ignored; the value is the ES query object.

Required: field (ignored), value (Elasticsearch query object)

{
  "filter": "custom",
  "field": "_",
  "value": {
    "wildcard": {
      "question": {
        "value": "*bitcoin*"
      }
    }
  }
}

Use sparingly. Prefer the structured filter types when possible — they're validated and optimized.

group_boost

Hierarchical boosting from a lookup index. Items found in lower-numbered groups get higher boost values. Only used in boost arrays.

The filter looks for paths {group}_01, {group}_02, ..., {group}_n in the lookup document, applying boost values that decrease linearly from max_boost (first group) to min_boost (last group).

Required: lookup_index, field, value, group Optional: min_boost (default 1), max_boost (default 5), n (default 10)

{
  "filter": "group_boost",
  "lookup_index": "polymarket-wallets",
  "field": "ai_labels_med",
  "value": "0xf68a281980f8c13828e84e147e3822381d6e5b1b",
  "group": "primary_labels",
  "min_boost": 1,
  "max_boost": 5,
  "n": 10
}

This boosts markets matching the user's top label groups — items matching primary_labels_01 get boost 5, items matching primary_labels_10 get boost 1.

terms_lookup

Filter using terms from another Elasticsearch document. Retrieves a list of values from a specified path in a lookup document and uses them to match the current index.

Required: lookup_index, field, value, path

{
  "filter": "terms_lookup",
  "lookup_index": "polymarket-wallets",
  "field": "ai_labels_med",
  "value": "0xf68a281980f8c13828e84e147e3822381d6e5b1b",
  "path": "primary_labels"
}

This filters items to match the user's primary label preferences from their wallet profile.

{
  "filter": "terms_lookup",
  "lookup_index": "following-graph",
  "field": "user_id",
  "value": "12345",
  "path": "following"
}

This filters farcaster-items to only show posts from users that FID 12345 follows.

Common lookup indices: polymarket-wallets, user-prefs, following-graph

console_account

Filter using data from a console account document in the console-accounts index. Commonly used for organization-level blacklists and whitelists.

Required: field, value (console account ID), path

{
  "filter": "console_account",
  "field": "user_id",
  "value": "account_123",
  "path": "blacklist"
}

Common paths: include_user_ids, include_item_ids, exclude_user_ids, exclude_item_ids, blacklist

Filterable Fields by Index

polymarket-items

polymarket-wallets

Sort fields: updated_at, pnl, volume

farcaster-items

zora-coins

AI Label Taxonomy

AI labels use the format model:prefix_label (e.g., mbd2:t_science_technology, tba2:f_positive).

Labels are applied at three confidence levels, each available as a filterable field on farcaster-items, polymarket-wallets, and zora-coins:

• ai_labels_high — High confidence
• ai_labels_med — Medium confidence (recommended default)
• ai_labels_low — Low confidence

Topics (19 labels, prefix t_)

Sentiment (3 labels, prefix f_)

Emotion (11 labels, prefix e_)

Moderation (11 labels)

Web3 (5 labels, prefix c_)

Market Sentiment (2 labels)

Content Quality (6 labels)

Recipes

Recipe 1: Trending Polymarket Markets

Active markets with high 24h volume, sorted by volume descending.

{
  "index": "polymarket-items",
  "size": 25,
  "sort_by": { "field": "volume_24hr", "order": "desc" },
  "include": [
    { "filter": "term", "field": "active", "value": true },
    { "filter": "numeric", "field": "volume_24hr", "operator": ">", "value": 50000 },
    { "filter": "numeric", "field": "liquidity_num", "operator": ">", "value": 10000 }
  ],
  "exclude": []
}

Recipe 2: Markets by Topic (AI Labels)

Polymarket markets about science/technology and crypto, excluding sports.

{
  "index": "polymarket-items",
  "size": 25,
  "sort_by": { "field": "volume_24hr", "order": "desc" },
  "include": [
    { "filter": "term", "field": "active", "value": true },
    { "filter": "terms", "field": "ai_labels_med", "value": ["mbd2:t_science_technology", "tba2:c_web3_defi"] }
  ],
  "exclude": [
    { "filter": "terms", "field": "ai_labels_med", "value": ["mbd2:t_sports"] }
  ]
}

Recipe 3: Exclude Closed Markets

Active-only markets with minimum liquidity, closed and restricted removed.

{
  "index": "polymarket-items",
  "size": 50,
  "sort_by": { "field": "liquidity_num", "order": "desc" },
  "include": [
    { "filter": "term", "field": "active", "value": true },
    { "filter": "numeric", "field": "liquidity_num", "operator": ">", "value": 5000 }
  ],
  "exclude": [
    { "filter": "term", "field": "closed", "value": true },
    { "filter": "term", "field": "restricted", "value": true }
  ]
}

Recipe 4: Markets Resolving Soon (Date Filter)

Markets ending within the next 30 days — useful for finding time-sensitive trading opportunities.

{
  "index": "polymarket-items",
  "size": 25,
  "sort_by": { "field": "end_date", "order": "asc" },
  "include": [
    { "filter": "term", "field": "active", "value": true },
    {
      "filter": "date",
      "field": "end_date",
      "value": {
        "date_from": "2026-02-12T00:00:00Z",
        "date_to": "2026-03-14T23:59:59Z"
      }
    },
    { "filter": "numeric", "field": "liquidity_num", "operator": ">", "value": 5000 }
  ],
  "exclude": []
}

Recipe 5: Semantic Search + Filters

Find markets semantically related to "artificial intelligence regulation" that also meet activity thresholds. Uses /search/semantic (not filter_and_sort).

{
  "index": "polymarket-items",
  "text": "artificial intelligence regulation and policy",
  "size": 20,
  "select_fields": ["item_id", "question", "liquidity_num", "volume_24hr", "best_ask"]
}

Note: The semantic endpoint does not support include/exclude filters or sort_by. If you need to combine semantic search with filtering, run semantic search first, collect the item IDs, then run a filter_and_sort query with { "filter": "terms", "field": "item_id", "value": [...ids] } in the include array.

Recipe 6: Boosting High-Liquidity Markets

Use the /search/boost endpoint to soft-boost high-liquidity and featured markets without hard-filtering them out.

{
  "index": "polymarket-items",
  "size": 30,
  "include": [
    { "filter": "term", "field": "active", "value": true },
    { "filter": "numeric", "field": "volume_24hr", "operator": ">", "value": 1000 }
  ],
  "boost": [
    { "filter": "numeric", "field": "liquidity_num", "operator": ">", "value": 50000, "boost": 3.0 },
    { "filter": "term", "field": "featured", "value": true, "boost": 1.5 },
    { "filter": "terms", "field": "ai_labels_med", "value": ["mbd2:f_market_sentiment_bullish"], "boost": 1.2 }
  ],
  "exclude": []
}

The boost endpoint does not support sort_by — results are ordered by relevance score, which incorporates both the base Elasticsearch score and boost multipliers.

Recipe 7: Discovering Available Values (frequent_values)

Before building filters, discover what values actually exist in a field. GET /search/frequent_values/{index}/{field}.

Discover AI labels on Polymarket:

curl -X GET "https://api.mbd.xyz/v3/studio/search/frequent_values/polymarket-items/ai_labels_med?size=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

[
  { "id": "mbd2:f_neutral", "count": 8765 },
  { "id": "mbd2:f_positive", "count": 5432 },
  { "id": "tba2:f_is_informative", "count": 4123 },
  { "id": "mbd2:t_science_technology", "count": 3876 },
  { "id": "mbd2:t_sports", "count": 2154 }
]

Discover popular Farcaster channels:

curl -X GET "https://api.mbd.xyz/v3/studio/search/frequent_values/farcaster-items/channels?size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Useful fields to explore:

• polymarket-items: sports_market_type, ai_labels_med
• polymarket-wallets: primary_labels, secondary_labels, ai_labels_med
• farcaster-items: lang, app, channels, ai_labels_med, publication_type
• zora-coins: zora_symbol, ai_labels_med, zora_media_content_type

Recipe 8: Personalized Boost with GroupBoost

Use the /search/boost endpoint with group_boost to boost markets matching a user's top label preferences. Items matching higher-ranked label groups get stronger boosts.

{
  "index": "polymarket-items",
  "size": 30,
  "include": [
    { "filter": "term", "field": "active", "value": true },
    { "filter": "numeric", "field": "liquidity_num", "operator": ">", "value": 5000 }
  ],
  "boost": [
    {
      "filter": "group_boost",
      "lookup_index": "polymarket-wallets",
      "field": "ai_labels_med",
      "value": "0xf68a281980f8c13828e84e147e3822381d6e5b1b",
      "group": "primary_labels",
      "min_boost": 1,
      "max_boost": 5,
      "n": 10
    },
    {
      "filter": "group_boost",
      "lookup_index": "polymarket-wallets",
      "field": "ai_labels_med",
      "value": "0xf68a281980f8c13828e84e147e3822381d6e5b1b",
      "group": "secondary_labels",
      "min_boost": 1,
      "max_boost": 3,
      "n": 10
    }
  ],
  "exclude": [
    { "filter": "term", "field": "closed", "value": true }
  ]
}

This gives markets matching the user's top primary labels up to 5x boost, and secondary labels up to 3x boost, creating a personalized relevance ranking directly at the search stage.

Recipe 9: Find High-Volume Wallets

Search polymarket-wallets for the most active traders by total volume.

{
  "index": "polymarket-wallets",
  "size": 25,
  "sort_by": { "field": "volume", "order": "desc" },
  "include": [
    { "filter": "numeric", "field": "volume", "operator": ">", "value": 100000 },
    { "filter": "not_null", "field": "pfp" }
  ],
  "exclude": []
}

Recipe 10: Find Wallets with Specific AI Label Preferences

Search polymarket-wallets for wallets whose AI-inferred interests include science/technology or crypto topics.

{
  "index": "polymarket-wallets",
  "size": 30,
  "sort_by": { "field": "pnl", "order": "desc" },
  "include": [
    { "filter": "terms", "field": "ai_labels_med", "value": ["mbd2:t_science_technology", "tba2:c_web3_defi"] },
    { "filter": "numeric", "field": "events_per_day", "operator": ">=", "value": 1 }
  ],
  "exclude": []
}

Recipe 11: High-Volume Farcaster Posts

Popular English posts with strong engagement, excluding spam.

{
  "index": "farcaster-items",
  "size": 20,
  "sort_by": { "field": "score_popular", "order": "desc" },
  "include": [
    { "filter": "term", "field": "lang", "value": "en" },
    { "filter": "numeric", "field": "score_popular", "operator": ">=", "value": 0.5 },
    { "filter": "numeric", "field": "num_like", "operator": ">=", "value": 10 }
  ],
  "exclude": [
    { "filter": "numeric", "field": "user_score_spam", "operator": ">", "value": 0.5 }
  ]
}

Recipe 12: New Zora Coins

Recently created Zora coins with meaningful market activity.

{
  "index": "zora-coins",
  "size": 30,
  "sort_by": { "field": "zora_created_at", "order": "desc" },
  "include": [
    {
      "filter": "date",
      "field": "zora_created_at",
      "value": { "date_from": "2026-02-05T00:00:00Z" }
    },
    { "filter": "numeric", "field": "zora_unique_holders", "operator": ">=", "value": 10 },
    { "filter": "numeric", "field": "zora_volume_24h", "operator": ">", "value": 100 }
  ],
  "exclude": [
    { "filter": "numeric", "field": "score_spam", "operator": ">", "value": 0.5 }
  ]
}