Skip to main content
Meilisearch can expose internal metrics through a GET /metrics endpoint in the Prometheus text exposition format. You can scrape this endpoint with Prometheus, visualize it in Grafana, or feed it into any compatible monitoring stack.
Meilisearch Cloud provides managed monitoring dashboards for search performance, operations, and indexing. The Prometheus endpoint is primarily useful for self-hosted instances that integrate with an existing Prometheus and Grafana setup.
The /metrics endpoint is an experimental feature. Metric names, labels, and behavior may change between Meilisearch versions without following semantic versioning. Track its status in the product discussion.

​
Enabling the endpoint

The endpoint is disabled by default. Enable it in one of three equivalent ways. At launch, with a CLI flag or environment variable: 
meilisearch --experimental-enable-metrics

export MEILI_EXPERIMENTAL_ENABLE_METRICS=true
At runtime, with the experimental features API (no restart required): 
curl -X PATCH "${MEILISEARCH_URL}/experimental-features" \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"metrics": true}'
The runtime setting is persisted in the database. On startup, the effective value is the CLI flag or environment variable OR the persisted value. This means a flag at launch enables the endpoint even if the persisted setting is false, and a persisted true survives restarts without the flag.

​
Authentication

If your instance has a master key configured, requests to /metrics must be authenticated:
  • Send the master key, or an API key with one of the metrics.get, metrics.*, or * actions, in the Authorization header.
  • The API key must be authorized on all indexes ("indexes": ["*"]). A key scoped to specific indexes is rejected with an invalid_api_key error.
If no master key is configured, no authentication is required. 
curl "${MEILISEARCH_URL}/metrics" \
  -H 'Authorization: Bearer MASTER_KEY'

​
Response format

A successful request returns 200 OK with a plain-text body (text/plain; version=0.0.4). Each metric is preceded by # HELP and # TYPE comment lines: 
# HELP meilisearch_index_docs_count Meilisearch Index Docs Count
# TYPE meilisearch_index_docs_count gauge
meilisearch_index_docs_count{index="movies"} 31944

​
Errors

SituationHTTPError code
Feature not enabled400feature_not_enabled
Missing Authorization header (when a master key is set)401missing_authorization_header
Key lacks the metrics.get action or is not scoped to all indexes403invalid_api_key

​
Metrics reference

All metric names are prefixed with meilisearch_. Most gauges are computed at scrape time, so their resolution equals your scrape interval.

​
Database and index stats

MetricTypeLabelsDescription
meilisearch_db_size_bytesgaugeNoneTotal size of the database on disk in bytes, including free space reclaimable by LMDB
meilisearch_used_db_size_bytesgaugeNonePortion of the database actually used, in bytes
meilisearch_index_countgaugeNoneNumber of indexes on the instance
meilisearch_index_docs_countgaugeindexNumber of documents per index
meilisearch_last_updategaugeNoneUnix timestamp of the last update to the instance
meilisearch_is_indexinggaugeNone1 if a task is currently being processed, otherwise 0

​
Task queue

MetricTypeLabelsDescription
meilisearch_nb_tasksgaugekind, valueTask counts broken down by kind="statuses", kind="types", and kind="indexes"
meilisearch_task_queue_latency_secondsgaugeNoneAge in seconds of the oldest task still enqueued or processing (0 when the queue is empty)
meilisearch_task_queue_max_sizegaugeNoneMaximum size of the task queue database, in bytes
meilisearch_task_queue_used_sizegaugeNoneCurrently used size of the task queue database, in bytes
meilisearch_task_queue_size_until_stop_registeringgaugeNoneRemaining bytes before the queue refuses new tasks
For meilisearch_nb_tasks, the value label depends on kind: task statuses (enqueued, processing, succeeded, failed, canceled), task types (such as documentAdditionOrUpdate or settingsUpdate), or index uids.

​
Batch and indexing progress

These gauges are recomputed on every scrape and can legitimately be absent from the output when nothing is being processed.
MetricTypeLabelsDescription
meilisearch_batch_running_progress_tracegaugebatch_uid, step_nameCompletion ratio (0 to 1) of each step of the currently processing batch
meilisearch_last_finished_batches_progress_trace_msgaugebatch_uid, step_nameDuration in ms of each step of the most recently finished batch. Step names are hierarchical, joined with > (for example processing tasks > indexing)
meilisearch_last_indexed_documents_countgaugebatch_uid, indexDocuments indexed, edited, and deleted by the last succeeded document batch
meilisearch_last_indexed_documents_duration_msgaugebatch_uid, indexWall-clock duration in ms of that same batch
The last_indexed_documents_* gauges are useful for computing indexing throughput. They only stay in the output while the batch is “fresh”: they disappear once more than the batch duration plus 5 minutes has elapsed. Use a scrape interval of 1 minute or less to reliably capture them.

​
HTTP traffic

MetricTypeLabelsDescription
meilisearch_http_requests_totalcountermethod, path, statusTotal HTTP requests. path is the route pattern (for example /indexes/{index_uid}/search), not the raw URL
meilisearch_http_response_time_secondshistogrammethod, pathResponse-time histogram, with buckets from 0.005 to 10 seconds
meilisearch_http_requests_total is counted for every request regardless of whether the metrics feature is enabled. meilisearch_http_response_time_seconds is only observed while the feature is enabled, and only for registered routes.

​
Search concurrency

MetricTypeLabelsDescription
meilisearch_search_queue_sizegaugeNoneCapacity of the search queue (configurable via --experimental-search-queue-size, default 1000)
meilisearch_searches_runninggaugeNoneNumber of searches currently executing
meilisearch_searches_waiting_to_be_processedgaugeNoneNumber of searches waiting in the queue

​
Feature-specific metrics

MetricTypeLabelsDescription
meilisearch_degraded_search_requestsgaugeNoneNumber of search requests that were degraded (hit the search cutoff before completing)
meilisearch_personalized_search_requestsgaugeNoneNumber of search requests that used personalization
meilisearch_chat_searches_totalcountertypeSearches performed by the chat completions route
meilisearch_chat_prompt_tokens_totalcounterworkspace, modelLLM prompt tokens consumed by the chat feature
meilisearch_chat_completion_tokens_totalcounterworkspace, modelLLM completion tokens consumed
meilisearch_chat_tokens_totalcounterworkspace, modelTotal tokens consumed (prompt plus completion)

​
Scraping with Prometheus

Add Meilisearch as a scrape target in your prometheus.yml. When a master key is configured, provide an API key with the metrics.get action on all indexes: 
scrape_configs:
  - job_name: meilisearch
    scrape_interval: 30s
    static_configs:
      - targets: ['MEILISEARCH_URL']
    authorization:
      type: Bearer
      credentials: 'MEILISEARCH_API_KEY'
You can then build dashboards in Grafana on top of these metrics, or configure alerting rules (for example, alerting when meilisearch_task_queue_size_until_stop_registering approaches zero).

​
Caveats

  • Experimental: the endpoint, metric names, and labels may change between versions without a deprecation period.
  • Snapshot resolution: most gauges are computed at scrape time, so their resolution equals your scrape interval.
  • Cardinality: per-index labels (such as meilisearch_index_docs_count) grow with your number of indexes. Instances with thousands of indexes will produce large responses.
  • Freshness window: the batch-progress and last_indexed_documents_* gauges are reset on every scrape and can be absent when nothing is processing or the last batch is too old.

​
Next steps

Monitoring overview

Managed monitoring dashboards on Meilisearch Cloud

Experimental features

Enable and manage experimental features

Configuration reference

All CLI options and environment variables