> ## Documentation Index > Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search in facets > Search for facet values within a given facet. > Use this to build autocomplete or refinement UIs for facet filters. ## OpenAPI ````yaml /assets/open-api/meilisearch-openapi-mintlify.json post /indexes/{index_uid}/facet-search openapi: 3.1.0 info: title: meilisearch description: Meilisearch HTTP server contact: name: Quentin de Quelen email: quentin@dequelen.me license: name: MIT identifier: MIT version: 1.41.0 servers: - url: http://localhost:7700 description: Local server. security: [] tags: - name: Stats description: >- Stats gives extended information and metrics about indexes and the Meilisearch database. - name: Health description: >- The health check endpoint enables you to periodically test the health of your Meilisearch instance. - name: Version description: Returns the version of the running Meilisearch instance. - name: Backups description: >- Meilisearch offers two types of backups: snapshots and dumps. Snapshots are mainly intended as a safeguard, while dumps are useful when migrating Meilisearch. - name: Export description: >- Export documents and settings from this instance to a remote Meilisearch server. - name: Async task management description: >- Routes for listing and managing batches and tasks (asynchronous operations). - name: Chats description: The `/chats` route allows you to manage chat workspaces. - name: Tasks description: >- The tasks route gives information about the progress of the [asynchronous operations](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html). - name: Batches description: >- Meilisearch groups compatible tasks ([asynchronous operations](https://www.meilisearch.com/docs/learn/async/asynchronous_operations)) into batches for efficient processing. For example, multiple document additions to the same index may be batched together. The /batches routes give information about the progress of these batches and let you monitor batch progress and performance. - name: Indexes description: >- An index is an entity that gathers a set of [documents](https://www.meilisearch.com/docs/learn/getting_started/documents) with its own [settings](https://www.meilisearch.com/docs/reference/api/settings). Learn more about indexes. - name: Documents description: >- Documents are objects composed of fields that can store any type of data. Each field contains an attribute and its associated value. Documents are stored inside [indexes](https://www.meilisearch.com/docs/learn/getting_started/indexes). - name: Facet Search description: >- The `/facet-search` route allows you to search for facet values. Facet search supports prefix search and typo tolerance. The returned hits are sorted lexicographically in ascending order. You can configure how facets are sorted using the sortFacetValuesBy property of the faceting index settings. - name: Similar documents description: >- The /similar route uses AI-powered search to return a number of documents similar to a target document. Meilisearch exposes two routes for retrieving similar documents: POST and GET. In the majority of cases, POST will offer better performance and ease of use. - name: Settings description: >- Configure search and index behavior. Update all settings at once via PATCH /indexes/{indexUid}/settings, or use a sub-route to get, update, or reset a single setting. - name: Search description: >- Meilisearch exposes two routes to perform searches: - A POST route: this is the preferred route when using API authentication, as it allows [preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) caching and better performance. - A GET route: the usage of this route is discouraged, unless you have good reason to do otherwise (specific caching abilities for example) externalDocs: url: https://www.meilisearch.com/docs/reference/api/search description: Search API reference - name: Keys description: >- Manage API `keys` for a Meilisearch instance. Each key has a given set of permissions. You must have the master key or the default admin key to access the keys route. More information about the keys and their rights. Accessing any route under `/keys` without having set a master key will result in an error. - name: Logs description: >- Everything about retrieving or customizing logs. Currently [experimental](https://www.meilisearch.com/docs/learn/experimental/overview). - name: Multi-search description: >- The `/multi-search` route allows you to perform multiple search queries on one or more indexes by bundling them into a single HTTP request. Multi-search is also known as federated search. - name: Experimental features description: >- The `/experimental-features` route allows you to activate or deactivate some of Meilisearch's experimental features. This route is **synchronous**. This means that no task object will be returned, and any activated or deactivated features will be made available or unavailable immediately. - name: Network description: >- The `/network` route allows you to describe the topology of a network of Meilisearch instances. This route is **synchronous**. This means that no task object will be returned, and any change to the network will be made available immediately. - name: Webhooks description: >- The `/webhooks` route allows you to register endpoints to be called once tasks are processed. - name: Dynamic search rules description: >- The `/dynamic-search-rules` route allows you to configure dynamic search rules. paths: /indexes/{index_uid}/facet-search: post: tags: - Facet Search summary: Search in facets description: |- Search for facet values within a given facet. > Use this to build autocomplete or refinement UIs for facet filters. operationId: search parameters: - name: index_uid in: path description: Unique identifier of the index. required: true schema: type: string example: movies requestBody: content: application/json: schema: $ref: '#/components/schemas/FacetSearchQuery' required: true responses: '200': description: The documents are returned. content: application/json: schema: $ref: '#/components/schemas/SearchResult' example: hits: - id: 2770 title: American Pie 2 poster: >- https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg overview: >- The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest… release_date: 997405200 - id: 190859 title: American Sniper poster: >- https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg overview: >- U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime… release_date: 1418256000 offset: 0 limit: 2 estimatedTotalHits: 976 processingTimeMs: 35 query: 'american ' '401': description: The authorization header is missing. content: application/json: schema: $ref: '#/components/schemas/ResponseError' example: message: >- The Authorization header is missing. It must use the bearer authorization method. code: missing_authorization_header type: auth link: >- https://docs.meilisearch.com/errors#missing_authorization_header '404': description: Index not found. content: application/json: schema: $ref: '#/components/schemas/ResponseError' example: message: Index `movies` not found. code: index_not_found type: invalid_request link: https://docs.meilisearch.com/errors#index_not_found security: - Bearer: - search - '*' x-codeSamples: - lang: cURL source: |- curl \ -X POST 'MEILISEARCH_URL/indexes/books/facet-search' \ -H 'Content-Type: application/json' \ --data-binary '{ "facetQuery": "fiction", "facetName": "genres", "filter": "rating > 3" }' - lang: JS source: |- client.index('books').searchForFacetValues({ facetQuery: 'fiction', facetName: 'genres' filter: 'rating > 3' }) - lang: PHP source: |- $client->index('books')->facetSearch( (new FacetSearchQuery()) ->setFacetQuery('fiction') ->setFacetName('genres') ->setFilter(['rating > 3']) ); - lang: Python source: |- client.index('books').facet_search('genres', 'fiction', { 'filter': 'rating > 3' }) - lang: Java source: >- FacetSearchRequest fsr = FacetSearchRequest.builder().facetName("genres").facetQuery("fiction").filter(new String[]{"rating > 3"}).build(); client.index("books").facetSearch(fsr); - lang: Ruby source: >- client.index('books').facet_search('genres', 'fiction', filter: 'rating > 3') - lang: Go source: |- client.Index("books").FacetSearch(&meilisearch.FacetSearchRequest{ FacetQuery: "fiction", FacetName: "genres", Filter: "rating > 3", }) - lang: C# source: |- var query = new SearchFacetsQuery() { FacetQuery = "fiction", Filter = "rating > 3" }; await client.Index("books").FacetSearchAsync("genres", query); - lang: Rust source: |- let res = client.index("books") .facet_search("genres") .with_facet_query("fiction") .with_filter("rating > 3") .execute() .await .unwrap(); - lang: Dart source: |- await client.index('books').facetSearch( FacetSearchQuery( facetQuery: 'fiction', facetName: 'genres', filter: 'rating > 3', ), ); components: schemas: FacetSearchQuery: type: object description: Request body for searching facet values required: - facet_name properties: facet_query: type: - string - 'null' description: Query string to search for facet values facet_name: type: string description: Name of the facet to search q: type: - string - 'null' description: Query string to filter documents before facet search vector: type: - array - 'null' items: type: number format: float description: Custom query vector for semantic search media: description: Multimodal content for AI-powered search hybrid: oneOf: - type: 'null' - $ref: '#/components/schemas/HybridQuery' description: >- Hybrid search configuration that combines keyword search with semantic (vector) search. Set `semanticRatio` to balance between keyword matching (0.0) and semantic similarity (1.0). Requires an embedder to be configured in the index settings. filter: description: Filter expression to apply before facet search matching_strategy: $ref: '#/components/schemas/MatchingStrategy' description: Strategy used to match query terms attributes_to_search_on: type: - array - 'null' items: type: string description: Restrict search to specified attributes ranking_score_threshold: type: - number - 'null' format: double description: |- Minimum ranking score threshold (0.0 to 1.0) that documents must achieve to be considered when computing facet counts. Documents with scores below this threshold are excluded from facet value counts. locales: type: - array - 'null' items: $ref: '#/components/schemas/Locale' description: Languages to use for query processing exhaustive_facet_count: type: - boolean - 'null' description: Return exhaustive facet count instead of an estimate SearchResult: allOf: - $ref: '#/components/schemas/HitsInfo' description: >- Pagination info. Either offset/limit with `estimatedTotalHits`, or page/hitsPerPage with `totalHits` and `totalPages`. - type: object required: - hits - query - processingTimeMs properties: hits: type: array items: $ref: '#/components/schemas/SearchHit' description: >- Matching documents. Each hit contains document fields and, when requested, `_formatted`, `_matchesPosition`, `_rankingScore`, `_rankingScoreDetails`, `_geoDistance`. query: type: string description: Query string that produced this response. queryVector: type: - array - 'null' items: type: number format: float description: |- Query embedding used for the search. Present when vector or hybrid search was used. processingTimeMs: type: integer description: Time taken to process the query, in milliseconds. minimum: 0 facetDistribution: type: - object - 'null' description: >- Count of matching documents per facet value for each requested facet. Present when `facets` was set. additionalProperties: {} propertyNames: type: string facetStats: type: - object - 'null' description: |- Minimum and maximum numeric values per facet. Present for numeric facets when `facets` was set. additionalProperties: $ref: '#/components/schemas/FacetStats' propertyNames: type: string requestUid: type: - string - 'null' format: uuid description: UUID v7 identifying this search request. metadata: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchMetadata' description: >- Query and index metadata. Present when requested via the `Meili-Include-Metadata` header. performanceDetails: description: |- Timing breakdown per processing step. Present when `showPerformanceDetails` was true. remoteErrors: type: - object - 'null' description: Errors from remote shards. Federated search only. additionalProperties: $ref: '#/components/schemas/ResponseError' propertyNames: type: string semanticHitCount: type: - integer - 'null' format: u-int32 description: |- Exhaustive number of semantic search matches. AI-powered (hybrid/semantic) searches only. minimum: 0 description: Search response containing matching documents and metadata. ResponseError: type: object required: - message - code - type - link properties: message: type: string description: The error message. code: $ref: '#/components/schemas/Code' description: The error code. type: $ref: '#/components/schemas/ErrorType' description: The error type. link: type: string description: A link to the documentation about this specific error. HybridQuery: type: object description: 'Hybrid search: balance between keyword and semantic search.' required: - embedder properties: semanticRatio: type: number format: float description: Balance between keyword (0.0) and semantic (1.0) search. example: 0.5 embedder: type: string description: >- Name of the embedder from the index embedders setting (`embedder` in JSON). Used to vectorize the query. example: default MatchingStrategy: type: string description: >- This is unfortunately a duplication of the struct in . The reason why it is duplicated is because milli cannot depend on meilisearch. It would be cyclic imports. enum: - last - all - frequency Locale: type: string enum: - af - ak - am - ar - az - be - bn - bg - ca - cs - da - de - el - en - eo - et - fi - fr - gu - he - hi - hr - hu - hy - id - it - jv - ja - kn - ka - km - ko - la - lv - lt - ml - mr - mk - my - ne - nl - nb - or - pa - fa - pl - pt - ro - ru - si - sk - sl - sn - es - sr - sv - ta - te - tl - th - tk - tr - uk - ur - uz - vi - yi - zh - zu - afr - aka - amh - ara - aze - bel - ben - bul - cat - ces - dan - deu - ell - eng - epo - est - fin - fra - guj - heb - hin - hrv - hun - hye - ind - ita - jav - jpn - kan - kat - khm - kor - lat - lav - lit - mal - mar - mkd - mya - nep - nld - nob - ori - pan - pes - pol - por - ron - rus - sin - slk - slv - sna - spa - srp - swe - tam - tel - tgl - tha - tuk - tur - ukr - urd - uzb - vie - yid - zho - zul - cmn HitsInfo: oneOf: - type: object description: |- Page-based pagination with exact totals. Used when `page` or `hitsPerPage` was set in the request. required: - hitsPerPage - page - totalPages - totalHits properties: hitsPerPage: type: integer description: Number of results per page. minimum: 0 page: type: integer description: Current page index (1-based). minimum: 0 totalPages: type: integer description: Exhaustive total number of result pages. minimum: 0 totalHits: type: integer description: Exhaustive total number of matching documents. minimum: 0 - type: object description: |- Offset-based pagination with estimated total. Used when only `offset` and `limit` were set. required: - limit - offset - estimatedTotalHits properties: limit: type: integer description: Maximum number of documents returned. minimum: 0 offset: type: integer description: Number of documents skipped. minimum: 0 estimatedTotalHits: type: integer description: |- Estimated total number of matches (not exhaustive). Prioritizes relevancy and performance. minimum: 0 description: Pagination information for search results. SearchHit: type: object description: A single search result hit. properties: _formatted: type: object description: |- Document with highlighted and cropped attributes. Present when `attributesToHighlight` or `attributesToCrop` was set. additionalProperties: true _matchesPosition: type: - object - 'null' description: |- Byte offsets (`start`, `length`) of each matched term per attribute. Present when `showMatchesPosition` was true. additionalProperties: type: array items: $ref: '#/components/schemas/MatchBounds' propertyNames: type: string _rankingScore: type: - number - 'null' format: double description: >- Global [ranking score](https://www.meilisearch.com/docs/learn/relevancy/ranking_score) from 0.0 to 1.0. Present when `showRankingScore` was true. _rankingScoreDetails: type: - object - 'null' description: |- Per-rule score breakdown (words, typo, proximity, etc.). Present when `showRankingScoreDetails` was true. additionalProperties: {} propertyNames: type: string additionalProperties: description: |- Document fields as stored in the index. According to `attributesToRetrieve`. FacetStats: type: object description: >- Minimum and maximum numeric values for a facet. Present when the facet attribute has numeric values among matching documents. required: - min - max properties: min: type: number format: double description: Lowest numeric value for this facet among matching documents. max: type: number format: double description: Highest numeric value for this facet among matching documents. SearchMetadata: type: object description: Metadata about a search query (included when requested via header). required: - queryUid - indexUid properties: queryUid: type: string format: uuid description: Unique identifier for the query. indexUid: type: string description: UID of the index that was searched. primaryKey: type: - string - 'null' description: >- [Primary key](https://www.meilisearch.com/docs/learn/getting_started/primary_key) of the index. remote: type: - string - 'null' description: Remote that processed the query (federated search only). Code: type: string enum: - api_key_already_exists - api_key_not_found - bad_parameter - bad_request - database_size_limit_reached - document_not_found - dump_already_processing - dump_not_found - dump_process_failed - duplicate_index_found - immutable_api_key_actions - immutable_api_key_created_at - immutable_api_key_expires_at - immutable_api_key_indexes - immutable_api_key_key - immutable_api_key_uid - immutable_api_key_updated_at - immutable_index_created_at - immutable_index_updated_at - import_task_already_received - import_task_unknown_remote - receive_import_finished_unknown_remote - import_task_without_network_task - index_already_exists - index_creation_failed - index_not_found - index_primary_key_already_exists - index_primary_key_multiple_candidates_found - index_primary_key_no_candidate_found - internal - invalid_api_key - invalid_api_key_actions - invalid_api_key_description - invalid_api_key_expires_at - invalid_api_key_indexes - invalid_api_key_limit - invalid_api_key_name - invalid_api_key_offset - invalid_api_key_uid - invalid_content_type - invalid_document_csv_delimiter - invalid_document_fields - invalid_document_retrieve_vectors - missing_document_filter - missing_document_edition_function - inconsistent_document_change_headers - invalid_document_filter - invalid_document_sort - invalid_document_geo_field - invalid_document_geojson_field - invalid_header_value - invalid_vector_dimensions - invalid_vectors_type - invalid_document_id - invalid_document_ids - invalid_document_limit - invalid_document_offset - invalid_search_embedder - invalid_similar_embedder - invalid_search_hybrid_query - invalid_index_limit - invalid_index_offset - invalid_index_primary_key - invalid_index_custom_metadata - invalid_skip_creation - invalid_index_uid - invalid_multi_search_facets - invalid_multi_search_facets_by_index - invalid_multi_search_facet_order - invalid_multi_search_query_personalization - invalid_multi_search_query_show_performance_details - invalid_multi_search_federated - invalid_multi_search_federation_options - invalid_multi_search_max_values_per_facet - invalid_multi_search_merge_facets - invalid_multi_search_query_facets - invalid_multi_search_distinct - invalid_multi_search_query_pagination - invalid_multi_search_query_ranking_rules - invalid_multi_search_query_position - invalid_multi_search_remote - invalid_multi_search_weight - invalid_network_leader - invalid_network_remotes - invalid_network_shards - invalid_network_self - invalid_network_search_api_key - invalid_network_write_api_key - invalid_network_url - invalid_search_attributes_to_search_on - invalid_search_attributes_to_crop - invalid_search_attributes_to_highlight - invalid_similar_attributes_to_retrieve - invalid_similar_retrieve_vectors - invalid_search_attributes_to_retrieve - invalid_search_ranking_score_threshold - invalid_similar_ranking_score_threshold - invalid_search_retrieve_vectors - invalid_search_crop_length - invalid_search_crop_marker - invalid_search_facets - invalid_search_semantic_ratio - invalid_search_locales - invalid_facet_search_exhaustive_facet_count - invalid_facet_search_facet_name - invalid_similar_id - invalid_search_filter - invalid_similar_filter - invalid_search_highlight_post_tag - invalid_search_highlight_pre_tag - invalid_search_hits_per_page - invalid_similar_limit - invalid_search_limit - invalid_search_matching_strategy - invalid_similar_offset - invalid_search_offset - invalid_search_page - invalid_search_q - invalid_facet_search_query - invalid_facet_search_name - facet_search_disabled - invalid_search_vector - invalid_search_media - invalid_search_show_matches_position - invalid_search_show_ranking_score - invalid_similar_show_ranking_score - invalid_search_show_ranking_score_details - invalid_search_show_performance_details - invalid_search_use_network - invalid_similar_show_ranking_score_details - invalid_similar_show_performance_details - invalid_search_sort - invalid_search_distinct - invalid_search_personalize - invalid_search_personalize_user_context - invalid_search_media_and_vector - invalid_settings_displayed_attributes - invalid_settings_distinct_attribute - invalid_settings_proximity_precision - invalid_settings_facet_search - invalid_settings_prefix_search - invalid_settings_faceting - invalid_settings_filterable_attributes - invalid_settings_foreign_keys - invalid_settings_pagination - invalid_settings_search_cutoff_ms - invalid_settings_embedders - invalid_settings_ranking_rules - invalid_settings_searchable_attributes - invalid_settings_sortable_attributes - invalid_settings_stop_words - invalid_settings_non_separator_tokens - invalid_settings_separator_tokens - invalid_settings_dictionary - invalid_settings_synonyms - invalid_settings_typo_tolerance - invalid_settings_localized_attributes - invalid_state - invalid_store_file - invalid_swap_duplicate_index_found - invalid_swap_indexes - invalid_swap_rename - invalid_task_after_enqueued_at - invalid_task_after_finished_at - invalid_task_after_started_at - invalid_task_before_enqueued_at - invalid_task_before_finished_at - invalid_task_before_started_at - invalid_task_canceled_by - invalid_task_from - invalid_task_limit - invalid_task_reverse - invalid_task_statuses - invalid_task_types - invalid_task_uids - invalid_batch_uids - io_error - feature_not_enabled - malformed_payload - max_fields_limit_exceeded - missing_api_key_actions - missing_api_key_expires_at - missing_api_key_indexes - missing_authorization_header - missing_content_type - missing_document_id - missing_facet_search_facet_name - missing_index_uid - missing_master_key - missing_network_url - missing_payload - missing_search_hybrid - missing_swap_indexes - missing_task_filters - network_version_mismatch - no_space_left_on_device - not_leader - payload_too_large - remote_bad_response - remote_bad_request - remote_could_not_send_request - remote_invalid_api_key - remote_remote_error - remote_timeout - too_many_search_requests - task_not_found - task_file_not_found - batch_not_found - too_many_open_files - too_many_vectors - unexpected_network_previous_remotes - network_version_too_old - unprocessed_network_task - unretrievable_document - unretrievable_error_code - unsupported_media_type - invalid_s3_snapshot_request - invalid_s3_snapshot_parameters - s3_snapshot_server_error - vector_embedding_error - not_found_similar_id - invalid_document_edition_context - invalid_document_edition_function_filter - edit_documents_by_function_error - invalid_settings_index_chat - invalid_export_url - invalid_export_api_key - invalid_export_payload_size - invalid_export_indexes_patterns - invalid_export_index_filter - invalid_export_index_override_settings - unimplemented_external_function_calling - unimplemented_non_streaming_chat_completions - unimplemented_multi_choice_chat_completions - chat_not_found - invalid_chat_setting_document_template - invalid_chat_completion_org_id - invalid_chat_completion_project_id - invalid_chat_completion_api_version - invalid_chat_completion_deployment_id - invalid_chat_completion_source - invalid_chat_completion_base_api - invalid_chat_completion_api_key - invalid_chat_completion_prompts - invalid_chat_completion_system_prompt - invalid_chat_completion_search_description_prompt - invalid_chat_completion_search_query_param_prompt - invalid_chat_completion_search_filter_param_prompt - invalid_chat_completion_search_index_uid_param_prompt - invalid_chat_completion_pre_query_prompt - invalid_index_fields_filter - invalid_index_fields_filter_attribute_patterns - invalid_index_fields_filter_displayed - invalid_index_fields_filter_searchable - invalid_index_fields_filter_sortable - invalid_index_fields_filter_distinct - invalid_index_fields_filter_ranking_rule - invalid_index_fields_filter_filterable - requires_enterprise_edition - invalid_webhooks - invalid_webhook_url - invalid_webhook_headers - immutable_webhook - invalid_webhook_uuid - webhook_not_found - immutable_webhook_uuid - immutable_webhook_is_editable - invalid_dynamic_search_rule_offset - invalid_dynamic_search_rule_limit - invalid_dynamic_search_rule_filter - invalid_dynamic_search_rule_description - invalid_dynamic_search_rule_priority - invalid_dynamic_search_rule_active - invalid_dynamic_search_rule_conditions - invalid_dynamic_search_rule_actions - invalid_dynamic_search_rule_filter_attribute_patterns - invalid_dynamic_search_rule_filter_active - dynamic_search_rule_not_found ErrorType: type: string enum: - internal - invalid_request - auth - system MatchBounds: type: object description: |- Represents the position of a matching term in a document field. Used to indicate where query terms were found within attribute values, enabling features like highlighting and match position display. required: - start - length properties: start: type: integer description: |- The byte offset where the match begins within the attribute value. This is a zero-indexed position from the start of the string. minimum: 0 length: type: integer description: |- The length in bytes of the matched text. Combined with `start`, this defines the exact substring that matched the query term. minimum: 0 indices: type: - array - 'null' items: type: integer minimum: 0 description: |- Byte indices of individual matched characters when the match spans multiple positions (e.g., for prefix matches). This is `null` for simple contiguous matches. securitySchemes: Bearer: type: http scheme: bearer bearerFormat: Uuidv4, string or JWT description: >- An API key is a token that you provide when making API calls. Read more about [how to secure your project](https://www.meilisearch.com/docs/learn/security/basic_security). Include the API key to the `Authorization` header, for instance: ```bash -H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1' ``` If you use a SDK, ensure you instantiate the client with the API key, for instance with [JS SDK](https://github.com/meilisearch/meilisearch-js): ```js const client = new Meilisearch({ host: 'MEILISEARCH_URL', apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1' }); ``` ````