--- updatedAt: 2026-07-06T21:17:35.000Z agentTools: projectIndex: https://docs.getembed.ai/llms.txt --- # List Frequent Values Retrieve the most frequently occurring values for a specific field in an index. This endpoint is useful for discovering popular values in a field before building filters or queries. Common use cases include: - Discovering popular languages (`lang` field) - Finding trending channels/topics (`channels` field) - Identifying common AI labels (`ai_labels_med`, `ai_labels_high` fields) - Exploring active features of any keyword field **Data Scope**: Results are based on data from the last 7 days. This ensures you get recently relevant values rather than historical ones. The exact date field used varies by index: - `polymarket-trades`: `item_creation_timestamp` - `polymarket-items`: `created_at` - `polymarket-wallets`: `updated_at` - `token-items`: `zora_updated_at` - `kalshi-notifications`: `updated_at` - `polymarket-wallets`: `updated_at` - `token-items`: `last_updated` Results are sorted by frequency (highest first) and limited to the requested size (default 100). # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Studio APIs", "version": "1.0.0", "description": "The Studio APIs are the building-block services developers use to construct personalized feeds. Each endpoint handles one stage of the feed pipeline, and they are designed to be composed together:\n\n1. **Search** — Generate candidate items from Elasticsearch indices (Farcaster, Polymarket, Zora, Kalshi, Token) using filters, boosting, or semantic similarity.\n2. **Features** — Enrich candidates with ML-computed features (semantic similarity, topic matching, composite scores) based on a user profile.\n3. **Scoring** — Rerank candidates using trained ML models for personalized ordering.\n4. **Ranking** — Apply a 3-stage post-processing pipeline (sort, diversity, limits-by-field) to produce the final feed.\n5. **Stories** — Generate personalized narrative-driven content about market activity, bets, and price movements.\n\nThe typical flow is: **Search → Features → Scoring → Ranking**, with Stories as an optional parallel path for narrative content.\n\nThe [Algorithm DSL](https://www.npmjs.com/package/algo-dsl) wraps these endpoints with a fluent builder API, but you can also call them directly via REST.\n", "contact": { "name": "embed Team", "url": "https://www.mbd.xyz" }, "license": { "name": "MIT" } }, "servers": [ { "url": "https://api.mbd.xyz/v3/studio", "description": "embed Studio API" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Search", "description": "## Overview\n\nThe Search service generates candidate items from Elasticsearch indices. It supports four endpoints covering different retrieval strategies: filter-and-sort for structured queries, boost for relevance tuning, semantic for embedding-based similarity, and frequent-values for field exploration.\n\n## Key Concepts\n\n- **Indices**: Seven content indices are available — `polymarket-items` (social posts), `polymarket-items` (prediction markets), `polymarket-wallets` (Polymarket user wallets/profiles), `token-items` (creator coins), `kalshi-notifications` (Kalshi prediction markets via DFlow on Solana), `polymarket-wallets` (Kalshi user wallets/profiles), and `token-items` (multi-chain token data across Base, Ethereum, and Solana). Each index has its own set of filterable and sortable fields. See [Supported Indices](../docs/Data-Sources/supported-indices) for the full field reference.\n- **Filter Logic**: Filters go into `include` (AND — all must match), `exclude` (NOT — any match removes the item), or `boost` (SHOULD — matching items get a relevance multiplier) arrays.\n- **Filter Types**: 12 filter types are available — `term`, `terms`, `numeric`, `match`, `date`, `geo`, `is_null`, `not_null`, `custom`, `group_boost`, `terms_lookup`, and `console_account`.\n- **AI Labels**: Items are classified by MBD's AI pipeline into topics, sentiment, emotion, moderation, Web3, market sentiment, and content quality categories at three confidence levels (`ai_labels_high`, `ai_labels_med`, `ai_labels_low`).\n\n## Usage\n\nStart by choosing an index and a search mode. Use **Filter and Sort** for structured queries with exact filters and field-based ordering. Use **Boost** when you want soft relevance tuning without hard filtering. Use **Semantic** when you have a text query or embedding vector and want similarity-based retrieval. Use **Frequent Values** to discover what values exist in a field before building filters.\n" } ], "paths": { "/search/frequent_values/{index}/{field}": { "get": { "operationId": "listFrequentValues", "tags": [ "Search" ], "summary": "List Frequent Values", "description": "Retrieve the most frequently occurring values for a specific field in an index.\n\nThis endpoint is useful for discovering popular values in a field before building filters or queries. Common use cases include:\n- Discovering popular languages (`lang` field)\n- Finding trending channels/topics (`channels` field)\n- Identifying common AI labels (`ai_labels_med`, `ai_labels_high` fields)\n- Exploring active features of any keyword field\n\n**Data Scope**:\nResults are based on data from the last 7 days. This ensures you get recently relevant values rather than historical ones. The exact date field used varies by index:\n- `polymarket-items`: `item_creation_timestamp`\n- `polymarket-items`: `created_at`\n- `polymarket-wallets`: `updated_at`\n- `token-items`: `zora_updated_at`\n- `kalshi-notifications`: `updated_at`\n- `polymarket-wallets`: `updated_at`\n\nResults are sorted by frequency (highest first) and limited to the requested size (default 100).\n", "parameters": [ { "name": "index", "in": "path", "required": true, "description": "The Elasticsearch index to query for frequent values", "schema": { "type": "string", "enum": [ "polymarket-items", "polymarket-items", "polymarket-wallets", "token-items", "kalshi-notifications", "polymarket-wallets", "token-items" ] }, "example": "polymarket-items" }, { "name": "field", "in": "path", "required": true, "description": "The field within the index to analyze for frequent values. Works best with keyword or categorical fields.\n\n**Common fields by index**:\n- `polymarket-items`: `lang`, `app`, `channels`, `ai_labels_med`, `ai_labels_high`, `publication_type`\n- `polymarket-items`: `category`, `tags`, `currency`\n- `polymarket-wallets`: `primary_labels`, `secondary_labels`, `ai_labels_med`, `ai_labels_high`\n- `token-items`: `zora_symbol`, `zora_creator_farcaster_id`\n- `kalshi-notifications`: `tags`, `series_category`, `ai_labels_med`, `ai_labels_high`, `status`\n- `polymarket-wallets`: `primary_tags`, `primary_labels`, `ai_labels`\n- `token-items`: `chain`, `symbol`, `name`\n", "schema": { "type": "string" }, "example": "lang" }, { "name": "size", "in": "query", "required": false, "description": "Maximum number of frequent values to return. Results are limited to prevent excessive memory usage.", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 100 }, "example": 50 } ], "responses": { "200": { "description": "Successful list of frequent values", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FrequentValueItem" } }, "examples": { "languages": { "summary": "Frequent languages in farcaster items", "value": [ { "id": "en", "count": 15432 }, { "id": "es", "count": 3421 }, { "id": "fr", "count": 2156 }, { "id": "de", "count": 1843 }, { "id": "pt", "count": 1205 } ] }, "channels": { "summary": "Frequent channels/categories", "value": [ { "id": "dev", "count": 5678 }, { "id": "crypto", "count": 4321 }, { "id": "ai", "count": 3456 }, { "id": "markets", "count": 2987 } ] }, "ai_labels": { "summary": "Frequent AI labels", "value": [ { "id": "mbd2:f_neutral", "count": 8765 }, { "id": "mbd2:f_positive", "count": 5432 }, { "id": "tba2:f_is_informative", "count": 4123 }, { "id": "mbd2:t_technology", "count": 3876 } ] } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Console API key. Use `Bearer mbd-{your-api-key}`." } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Error response returned for 400/401 status codes.", "properties": { "detail": { "type": "string", "description": "Error details", "example": "Invalid filter type specified" } } }, "FrequentValueItem": { "type": "object", "required": [ "id", "count" ], "description": "A single frequent value result containing the field value and its occurrence count over the last 7 days.", "properties": { "id": { "type": "string", "description": "The field value", "example": "en" }, "count": { "type": "integer", "description": "Number of occurrences in the last 7 days", "example": 15432 } } } } } } ```