# prometheus-query

> A Javascript client for Prometheus query API

Latest version **3.5.1** (published 2025-09-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install prometheus-query
pnpm add prometheus-query
yarn add prometheus-query
bun add prometheus-query
```

## Health

**Score 40/100 (D)** — status: stable.

Positive: no vulnerabilities; high maintenance score.

Warnings: low downloads; no types; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.5.1 |
| Published | 2025-09-14 |
| First published | 2020-02-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 74 |
| Maintainers | samuelberthe |
| Keywords | prometheus, client, query, api, javascript, admin, series, range, label, timeseries, tsdb |

## Links

- npm: https://www.npmjs.com/package/prometheus-query
- Repository: https://github.com/samber/prometheus-query-js
- Homepage: https://github.com/samber/prometheus-query-js#readme
- Issues: https://github.com/samber/prometheus-query-js/issues
- npm.io page: https://npm.io/package/prometheus-query

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 3.5.1 (latest) — 2025-09-14
- 3.0.0-beta.1 (beta) — 2021-02-07
- 3.5.0 — 2025-04-16
- 3.4.1 — 2024-11-11
- 3.4.0 — 2024-01-11
- 3.3.3 — 2023-11-17
- 3.3.2 — 2023-04-25
- 3.3.1 — 2023-03-10
- 3.3.0 — 2022-10-02
- 3.2.5 — 2022-07-23
- 3.2.4 — 2022-07-23
- 3.2.3 — 2022-04-19
- 3.2.2 — 2022-04-18
- 3.2.1 — 2022-03-17
- 3.2.0 — 2021-10-17
- … 15 more at https://npm.io/package/prometheus-query/versions

## README

# Welcome to prometheus-query  👋
[![NPM version](https://img.shields.io/npm/v/prometheus-query.svg?style=flat-square)](https://npmjs.org/package/prometheus-query)
<a href="https://www.jsdelivr.com/package/npm/prometheus-query"><img src="https://data.jsdelivr.com/v1/package/npm/prometheus-query/badge" alt="jsDelivr Downloads"></img></a>
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#)

> A Javascript client for Prometheus **query** API.

## ✨ Features

- Thin & **minimal low-level HTTP client** to interact with Prometheus's API
- Works both on the **browser** and **node.js**
- **UMD compatible**, you can use it with any module loader
- Supports **query** and admin [APIs](https://prometheus.io/docs/prometheus/latest/querying/api/)

⚠️ This library does not export metrics. Please use [prom-client](https://github.com/siimon/prom-client) instead.

For building shiny Charts, you may like this chartjs plugin: [samber/chartjs-plugin-datasource-prometheus](https://github.com/samber/chartjs-plugin-datasource-prometheus).

<div align="center">
  <hr>
  <sup><b>Sponsored by:</b></sup>
  <br>
  <a href="https://www.dash0.com?utm_campaign=148395251-samber%20github%20sponsorship&utm_source=github&utm_medium=sponsorship&utm_content=samber">
    <div>
      <img src="https://github.com/user-attachments/assets/b1f2e876-0954-4dc3-824d-935d29ba8f3f" width="200" alt="Dash0">
    </div>
    <div>
      100% OpenTelemetry-native observability platform<br>Simple to use, built on open standards, and designed for full cost control
    </div>
  </a>
  <hr>
</div>

## 🚀 Install

### NodeJS

```sh
npm install prometheus-query
```

### Upgrade from v2 to v3

- `prometheus-query-js` has been recoded into Typescript.
- Type definitions.
- API update:
  - `PrometheusQuery` is not the default export anymore.
  - `PrometheusQuery` has been renamed as `PrometheusDriver`.
  - [See examples](./examples/nodejs/app.ts)

### Browser

```html
<script src="https://cdn.jsdelivr.net/npm/prometheus-query/dist/prometheus-query.umd.min.js"></script>

<script type="application/javacript">
	const prom = new Prometheus.PrometheusDriver(...);
</script>
```

## 💡 Quick start

```js
import { PrometheusDriver } from 'prometheus-query';

const prom = new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    baseURL: "/api/v1" // default value
});
```

### Instant query

```js
// last `up` value
const q = 'up{instance="demo.do.prometheus.io:9090",job="node"}';
prom.instantQuery(q)
    .then((res) => {
        const series = res.result;
        series.forEach((serie) => {
            console.log("Serie:", serie.metric.toString());
            console.log("Time:", serie.value.time);
            console.log("Value:", serie.value.value);
        });
    })
    .catch(console.error);
```

Output:

```txt
Serie: up{instance="prometheus.demo.do.prometheus.io:9100", job="node"}
Time: Sun Feb 16 2020 18:33:59 GMT+0100 (Central European Standard Time)
Value: 1
```

### Range query

```js
// up during past 24h
const q = 'up';
const start = new Date().getTime() - 24 * 60 * 60 * 1000;
const end = new Date();
const step = 6 * 60 * 60; // 1 point every 6 hours

prom.rangeQuery(q, start, end, step)
    .then((res) => {
        const series = res.result;
        series.forEach((serie) => {
            console.log("Serie:", serie.metric.toString());
            console.log("Values:\n" + serie.values.join('\n'));
        });
    })
    .catch(console.error);
```

Output:

```txt
Serie: up{instance="prometheus.demo.do.prometheus.io:9090", job="prometheus"}
Values:
Sat Feb 15 2020 18:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 00:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 06:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 12:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 18:21:47 GMT+0100 (Central European Standard Time): 1

Serie: up{instance="prometheus.demo.do.prometheus.io:9093", job="alertmanager"}
Values:
Sat Feb 15 2020 18:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 00:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 06:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 12:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 18:21:47 GMT+0100 (Central European Standard Time): 1

Serie: up{instance="prometheus.demo.do.prometheus.io:9100", job="node"}
Values:
Sat Feb 15 2020 18:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 00:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 06:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 12:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 18:20:51 GMT+0100 (Central European Standard Time): 1
```

### List series matching query

```js
const match = 'up';
const start = new Date().getTime() - 24 * 60 * 60 * 1000;
const end = new Date();

prom.series(match, start, end)
    .then((res) => {
        console.log('Series:');
        console.log(res.join('\n'));
    })
    .catch(console.error);
```

Output:

```txt
up{instance="demo.do.prometheus.io:9090", job="prometheus"}
up{instance="demo.do.prometheus.io:9093", job="alertmanager"}
up{instance="demo.do.prometheus.io:9100", job="node"}
```

### List all active alerts

```js
prom.alerts()
    .then(console.log)
    .catch(console.error);
```

Output:

```js
[
  Alert {
    activeAt: 2019-11-14T20:04:36.629Z,
    annotations: {},
    labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'alertmanager' },
    state: 'firing',
    value: 1
  },
  Alert {
    activeAt: 2019-11-14T20:04:36.629Z,
    annotations: {},
    labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'node' },
    state: 'firing',
    value: 1
  },
  Alert {
    activeAt: 2019-11-14T20:04:36.629Z,
    annotations: {},
    labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'prometheus' },
    state: 'firing',
    value: 1
  },
  Alert {
    activeAt: 2019-11-14T20:04:36.629Z,
    annotations: {},
    labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'pushgateway' },
    state: 'firing',
    value: 1
  }
]
```

### Authenticated query

Using basic auth:

```ts
new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    auth: {
        username: 'foo',
        password: 'bar'
    }
});
```

Using cookies:

```ts
new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    withCredentials: true
});
```

### Proxy

```ts
new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    proxy: {
        host: 'proxy.acme.com',
        port: 8080
    }
});
```

### Hook HTTP requests and responses

```ts
new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    proxy: {
        host: 'proxy.acme.com',
        port: 8080
    },
    requestInterceptor: {
        onFulfilled: (config: AxiosRequestConfig) => {
            return config;
        },
        onRejected: (error: any) => {
            return Promise.reject(error.message);
        }
    },
    responseInterceptor: {
        onFulfilled: (res: AxiosResponse) => {
            return res;
        },
        onRejected: (error: any) => {
            return Promise.reject(error.message);
        }
    }
});
```

## 🔐 Security advisory

If you open a Prometheus instance on Internet, it would be a good idea to block some routes.

Start by blocking `/api/v1/admin`. I'm pretty sure allowing only `/api/v1/query` and `/api/v1/query_range` will match your needs.

Also don't use Prometheus as a multitenant timeseries database!

At your own risk... 😘

## 🤝 Contributing

The Prometheus Query client is open source and contributions from the community (you!) are welcome.

There are many ways to contribute: writing code, documentation, reporting issues...

[How-to](./CONTRIBUTING.md)

## Author

👤 **Samuel Berthe**

* Twitter: [@samuelberthe](https://twitter.com/samuelberthe)
* Github: [@samber](https://github.com/samber)

## 💫 Show your support

Give a ⭐️ if this project helped you!

[![support us](https://c5.patreon.com/external/logo/become_a_patron_button.png)](https://www.patreon.com/samber)

## 📝 License

Copyright © 2020 [Samuel Berthe](https://github.com/samber).

This project is [MIT](./LICENSE) licensed.

---
_Source: https://npm.io/package/prometheus-query · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._