Since the update to Prometheus 2.0, the documentation still has to catch up. Because I’ve been debugging a custom written exporter, some unwanted metrics landed in my Prometheus.

This is how to delete those series.

Update: The official API documentation can be found here: prometheus.io/docs

Enable the Prometheus Admin API

Deleting the metrics is only available over the Admin API. You can enable it with a flag. Just edit your Prometheus start-up script and add:

--web.enable-admin-api

My full CLI command now looks like this:

/usr/bin/prometheus --web.enable-admin-api --config.file=/etc/prometheus/prometheus.yaml --storage.tsdb.path=/var/lib/prometheus2 --storage.tsdb.retention.time=365d --web.external-url=https://xxx[redacted]xxx/prometheus/ --web.console.templates=/usr/share/prometheus/consoles --web.console.libraries=/usr/share/prometheus/console_libraries

Delete the Time Series

As you’ve probably noticed, I use a custom URL for Prometheus. Showing an example on how to delete the up series for the instance amazing_instance:9922

Without a custom URL

curl -s -X POST -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up{instance="amazing_instance:9922"}'

With a custom URL (example: /prometheus)

curl -s -X POST -g 'http://localhost:9090/prometheus/api/v1/admin/tsdb/delete_series?match[]=up{instance="amazing_instance:9922"}'

A successful delete returns HTTP 204 with an empty body, so don’t be surprised when nothing comes back.

You can also scope the delete to a time window with the optional start and end parameters (RFC3339 or Unix timestamps). Leave them off and the matched series are deleted across their entire history.

Free the Disk Space

Here’s the part the delete call doesn’t tell you: delete_series only tombstones the samples. The data stays on disk and is reclaimed on the next block compaction. If you want the space back now, call clean_tombstones:

curl -s -X POST 'http://localhost:9090/api/v1/admin/tsdb/clean_tombstones'

This also returns 204 with no body. Don’t cron this or run it after every delete, since it forces a heavy rewrite and normal compaction frees the space anyway. Only run it when you need the disk back right now.

Gotchas

A few things that trip people up:

  • --web.enable-admin-api is dangerous. It exposes destructive endpoints with no built-in auth, TLS, or CSRF protection, and it’s off by default for good reason. Keep it behind a reverse proxy or a network ACL, never on a public network.
  • Matchers are OR’d, so a series matching any one of your match[] selectors gets deleted. Double-check before firing.
  • Pass curl -g. The {, }, = and " in a selector are glob metacharacters, and -g disables globbing so your matcher survives intact.
  • Deletes are eventually consistent. A 204 doesn’t mean the series is gone instantly; it can still surface in metadata and label queries until compaction or a tombstone cleanup catches up.
  • It only touches the local TSDB. Remote-write and remote-read backends (Thanos, Mimir, Cortex) keep their copy and have their own deletion APIs.

Not working anymore

Keeping these here for historical reference, however these commands don’t work anymore

The old v2 command (no custom URL)

curl --silent -H "Content-Type: application/json" -X POST -d '{"matchers":[{"type":"EQ","name":"__name__","value":"up"}]}' 'http://localhost:9090/api/v2/admin/tsdb/delete_series'|jq .

The old v2 command (custom URL)

curl --silent -H "Content-Type: application/json" -X POST -d '{"matchers":[{"type":"EQ","name":"__name__","value":"up"}]}' 'http://localhost:9090/prometheus/api/v2/admin/tsdb/delete_series'|jq .

Other Matchers

Looking at the Source Code, the following matchers are available:

  • Equals: EQ
  • Not equal: NEQ
  • Regex match: RE
  • Regex not match: NRE

Updates

This article was updated on:

  • 2017: Changed the link to the source code, since it’s bound to be fluid. This way, you will know what to look for in the current master.
  • 2020-02-17: Updated the delete commands with the ones that work now. Added the link to the official API documentation.
  • 2026-07-18: Verified everything still holds on current Prometheus (3.x). Added the clean_tombstones step to actually free disk, documented the optional start/end parameters, and wrote up the gotchas. Fixed the deprecated --storage.tsdb.retention flag to --storage.tsdb.retention.time.