Debug search performance

Use the showPerformanceDetails parameter to get detailed timing breakdowns for each stage of a search query.

When a search query is slower than expected, it can be difficult to tell which part of the pipeline is responsible. The showPerformanceDetails parameter returns per-stage timing information so you can pinpoint bottlenecks without guesswork.

How it works

Set showPerformanceDetails to true in any search request. Meilisearch will include a performanceDetails object in the response, breaking down how much time each stage of the search pipeline consumed.

This parameter is supported on all search routes:

• POST /indexes/{indexUid}/search
• GET /indexes/{indexUid}/search
• POST /multi-search
• POST /indexes/{indexUid}/similar
• GET /indexes/{indexUid}/similar

Basic usage

Add showPerformanceDetails to a standard search request:

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "glass",
    "showPerformanceDetails": true
  }'

The response includes the usual search results along with a performanceDetails object:

{
  "hits": [
    { "id": 1, "title": "Glass Onion" }
  ],
  "query": "glass",
  "processingTimeMs": 4,
  "performanceDetails": {
    "wait for permit": "295.29µs",
    "search > tokenize": "436.67µs",
    "search > resolve universe": "649.00µs",
    "search > keyword search": "515.71µs",
    "search > format": "288.54µs",
    "search": "3.56ms"
  }
}

Understanding performance stages

Each key in performanceDetails represents a stage of the search pipeline. Stage names are hierarchical, using > as a separator (e.g., search > keyword search).

Top-level stages

Stage	Description
wait for permit	Time waiting for a search permit. Meilisearch limits concurrent searches, so a high value here means your instance is handling too many simultaneous queries.
search	Total time for the entire search operation, including all sub-stages below.
similar	Total time for a similar documents request (instead of search).

Search sub-stages

These appear as children of the search stage. Not all stages appear in every query; Meilisearch only reports stages that were actually executed.

Stage	Description
search > tokenize	Breaking the query string into individual tokens. Typically very fast unless the query is unusually long.
search > embed	Generating vector embeddings for the query. Only appears when using hybrid or semantic search. Duration depends on your embedder provider and network latency.
search > filter	Evaluating filter expressions to narrow the candidate set. Complex filters or many filterable attributes increase this time.
search > resolve universe	Determining the initial set of candidate documents. This combines filter results with the full document set to establish which documents are eligible for ranking.
search > keyword search	Running keyword matching against candidates. Often the most significant stage for broad queries on large datasets.
search > placeholder search	Retrieving documents when the query is empty (placeholder search). Appears instead of keyword search when q is empty or missing.
search > semantic search	Running vector similarity search against candidates. Only appears when using hybrid or semantic search.
search > personalization	Applying search personalization to re-rank results based on user context. Only appears when personalization is configured.
search > facet distribution	Computing facet value counts for the facets parameter. Cost scales with the number of faceted attributes and unique values. See maxValuesPerFacet.
search > format	Formatting results: highlighting, cropping, building the response payload. Cost scales with the number of attributes to highlight/crop and the size of document fields.

Federated search stages

When using showPerformanceDetails at the federation level, you see these stages instead:

Stage	Description
federating results > partition queries	Organizing queries by index and remote host.
federating results > start remote search	Initiating search requests to remote Meilisearch instances. Only appears when using network search.
federating results > execute local search	Executing queries against local indexes.
federating results > wait for remote results	Waiting for remote instances to respond. High values indicate network latency or slow remote instances.
federating results > merge results	Merging and deduplicating results from all sources into a single ranked list.
federating results > hydrate documents	Fetching full document data, including linked index joins.
federating results > merge facets	Combining facet distributions from all sources.

Multiple occurrences of the same stage (e.g., multiple search > keyword search in a federated query) are automatically accumulated into a single total duration.

Multi-search

In multi-search requests, set showPerformanceDetails on each individual query that you want to profile:

curl \
  -X POST 'MEILISEARCH_URL/multi-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "queries": [
      {
        "indexUid": "movies",
        "q": "glass",
        "showPerformanceDetails": true
      },
      {
        "indexUid": "actors",
        "q": "samuel",
        "showPerformanceDetails": true
      }
    ]
  }'

Each result in the response includes its own performanceDetails, letting you compare timing across indexes and queries.

Federated search

For federated multi-search, set showPerformanceDetails in the federation object to get timing details for the combined search:

curl \
  -X POST 'MEILISEARCH_URL/multi-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "federation": {
      "showPerformanceDetails": true
    },
    "queries": [
      { "indexUid": "movies", "q": "glass" },
      { "indexUid": "books", "q": "glass" }
    ]
  }'

Similar documents

The similar documents endpoint also supports showPerformanceDetails:

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/similar' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "id": "143",
    "showPerformanceDetails": true
  }'

Practical tips

Identify the bottleneck

Look for the stage with the highest duration. Common patterns:

• High wait for permit: your instance is overloaded with concurrent searches. Scale your hardware or reduce query volume.
• High search > filter: complex filter expressions or too many filterable attributes. Use granular filterable attributes to disable unused filter features.
• High search > resolve universe: complex filters or geo constraints are expensive. Simplify filters or ensure your filterable attributes are correctly configured.
• High search > keyword search: the query matches too many candidates. Add stop words, limit searchable attributes, or lower maxTotalHits.
• High search > embed: your embedder is slow. Consider switching to a faster model, using a local embedder for search with composite embedders, or caching embeddings.
• High search > facet distribution: too many faceted attributes or high maxValuesPerFacet. Lower it to the number of facet values you actually display.
• High search > format: large attributesToRetrieve, attributesToHighlight, or attributesToCrop. Reduce to only the fields your UI needs.
• High federating results > wait for remote results: network latency to remote instances. Check network connectivity or colocate instances.

Compare before and after

Use showPerformanceDetails before and after configuration changes (adding stop words, adjusting searchable attributes, modifying the search cutoff) to measure the impact of each optimization.

Disable in production

Collecting performance details adds a small amount of overhead to each search request. Use this parameter for debugging and profiling, then remove it from production queries.

Performance tuning

Optimize search speed and relevancy for large datasets

Ranking pipeline

Understand how Meilisearch ranks search results

Configure search cutoff

Set time limits to guarantee consistent response times

Search API reference

Full API reference for the search endpoint