Prometheus endpoint

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

Situation	HTTP	Error code
Feature not enabled	400	`feature_not_enabled`
Missing `Authorization` header (when a master key is set)	401	`missing_authorization_header`
Key lacks the `metrics.get` action or is not scoped to all indexes	403	`invalid_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

Metric	Type	Labels	Description
`meilisearch_db_size_bytes`	gauge	None	Total size of the database on disk in bytes, including free space reclaimable by LMDB
`meilisearch_used_db_size_bytes`	gauge	None	Portion of the database actually used, in bytes
`meilisearch_index_count`	gauge	None	Number of indexes on the instance
`meilisearch_index_docs_count`	gauge	`index`	Number of documents per index
`meilisearch_last_update`	gauge	None	Unix timestamp of the last update to the instance
`meilisearch_is_indexing`	gauge	None	`1` if a task is currently being processed, otherwise `0`

Task queue

Metric	Type	Labels	Description
`meilisearch_nb_tasks`	gauge	`kind`, `value`	Task counts broken down by `kind="statuses"`, `kind="types"`, and `kind="indexes"`
`meilisearch_task_queue_latency_seconds`	gauge	None	Age in seconds of the oldest task still enqueued or processing (`0` when the queue is empty)
`meilisearch_task_queue_max_size`	gauge	None	Maximum size of the task queue database, in bytes
`meilisearch_task_queue_used_size`	gauge	None	Currently used size of the task queue database, in bytes
`meilisearch_task_queue_size_until_stop_registering`	gauge	None	Remaining 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.

Metric	Type	Labels	Description
`meilisearch_batch_running_progress_trace`	gauge	`batch_uid`, `step_name`	Completion ratio (0 to 1) of each step of the currently processing batch
`meilisearch_last_finished_batches_progress_trace_ms`	gauge	`batch_uid`, `step_name`	Duration 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_count`	gauge	`batch_uid`, `index`	Documents indexed, edited, and deleted by the last succeeded document batch
`meilisearch_last_indexed_documents_duration_ms`	gauge	`batch_uid`, `index`	Wall-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

Metric	Type	Labels	Description
`meilisearch_http_requests_total`	counter	`method`, `path`, `status`	Total HTTP requests. `path` is the route pattern (for example `/indexes/{index_uid}/search`), not the raw URL
`meilisearch_http_response_time_seconds`	histogram	`method`, `path`	Response-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

Metric	Type	Labels	Description
`meilisearch_search_queue_size`	gauge	None	Capacity of the search queue (configurable via `--experimental-search-queue-size`, default 1000)
`meilisearch_searches_running`	gauge	None	Number of searches currently executing
`meilisearch_searches_waiting_to_be_processed`	gauge	None	Number of searches waiting in the queue

Feature-specific metrics

Metric	Type	Labels	Description
`meilisearch_degraded_search_requests`	gauge	None	Number of search requests that were degraded (hit the search cutoff before completing)
`meilisearch_personalized_search_requests`	gauge	None	Number of search requests that used personalization
`meilisearch_chat_searches_total`	counter	`type`	Searches performed by the chat completions route
`meilisearch_chat_prompt_tokens_total`	counter	`workspace`, `model`	LLM prompt tokens consumed by the chat feature
`meilisearch_chat_completion_tokens_total`	counter	`workspace`, `model`	LLM completion tokens consumed
`meilisearch_chat_tokens_total`	counter	`workspace`, `model`	Total 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

Capabilities

Full-text search

Hybrid and semantic search

Geo search

Conversational search

Multi-search

Filtering, sorting, and faceting

Personalization

Analytics

Security and tenant tokens

Search rules

Platform

Indexing

Enabling the endpoint

Authentication

Response format

Errors

Metrics reference

Database and index stats

Task queue

Batch and indexing progress

HTTP traffic

Search concurrency

Feature-specific metrics

Scraping with Prometheus

Caveats

Next steps

Monitoring overview

Experimental features

Configuration reference

​Enabling the endpoint

​Authentication

​Response format

​Errors

​Metrics reference

​Database and index stats

​Task queue

​Batch and indexing progress

​HTTP traffic

​Search concurrency

​Feature-specific metrics

​Scraping with Prometheus

​Caveats

​Next steps

Monitoring overview

Experimental features

Configuration reference

Enabling the endpoint

Authentication

Response format

Errors

Metrics reference

Database and index stats

Task queue

Batch and indexing progress

HTTP traffic

Search concurrency

Feature-specific metrics

Scraping with Prometheus

Caveats

Next steps