# Prometheus (/docs/reference/api/apps/prometheus)



Prometheus [#prometheus]

Install the Prometheus app first. Queries need read permission. Remote write needs write permission.

The service exposes Prometheus remote write and query-compatible endpoints under `/prometheus/api/v1`. The Prometheus app must be installed on the target cluster before any endpoint in this group can be used. See the [Prometheus guide](/docs/integrations/prometheus) for configuration and supported endpoints.

Query parameters [#query-parameters]

GET methods accept URL parameters. POST methods accept URL parameters plus a form or JSON body.
Use `--data-urlencode` for PromQL expressions and repeated `match[]` selectors.

| Methods                                            | Parameters                                                                       |
| -------------------------------------------------- | -------------------------------------------------------------------------------- |
| `/query`                                           | Required `query`. Optional `time` selects the evaluation instant                 |
| `/query_range`                                     | Required `query`, `start`, `end`, and `step`                                     |
| `/labels`, `/label/{label_name}/values`, `/series` | Optional `match[]`, `start`, and `end`. `/series` requires at least one selector |
| `/metadata`                                        | Optional `metric` filters the metric name                                        |
| `/status/buildinfo`                                | No query parameters beyond authentication scope                                  |

Timestamps accept Unix seconds or RFC 3339. Range steps accept seconds or supported duration strings.
The service implements a PromQL subset. See [Prometheus](/docs/integrations/prometheus) for supported expressions and limits.
Errors use the Prometheus response envelope with `status: "error"`, `errorType`, and `error`.

GET `/prometheus/api/v1/query` [#get-prometheusapiv1query]

Read Prometheus query.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus query.
curl -X GET "https://api.rawtree.com/prometheus/api/v1/query?database=analytics&query=up" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": []
  }
}
```

POST `/prometheus/api/v1/query` [#post-prometheusapiv1query]

Read Prometheus query.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus query.
curl -X POST "https://api.rawtree.com/prometheus/api/v1/query?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  --data-urlencode 'query=up'
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": []
  }
}
```

GET `/prometheus/api/v1/query_range` [#get-prometheusapiv1query_range]

Read Prometheus query\_range.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus query_range.
curl -X GET "https://api.rawtree.com/prometheus/api/v1/query_range?database=analytics&query=up&start=1794214800&end=1794218400&step=60" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": []
  }
}
```

POST `/prometheus/api/v1/query_range` [#post-prometheusapiv1query_range]

Read Prometheus query\_range.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus query_range.
curl -X POST "https://api.rawtree.com/prometheus/api/v1/query_range?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  --data-urlencode 'query=up' \
  --data-urlencode 'start=1794214800' \
  --data-urlencode 'end=1794218400' \
  --data-urlencode 'step=60'
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": []
  }
}
```

GET `/prometheus/api/v1/labels` [#get-prometheusapiv1labels]

Read Prometheus labels.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus labels.
curl -X GET "https://api.rawtree.com/prometheus/api/v1/labels?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": []
}
```

POST `/prometheus/api/v1/labels` [#post-prometheusapiv1labels]

Read Prometheus labels.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus labels.
curl -X POST "https://api.rawtree.com/prometheus/api/v1/labels?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": []
}
```

GET `/prometheus/api/v1/label/{label_name}/values` [#get-prometheusapiv1labellabel_namevalues]

Read the values for a Prometheus label.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read the values for a Prometheus label.
curl -X GET "https://api.rawtree.com/prometheus/api/v1/label/job/values?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": []
}
```

POST `/prometheus/api/v1/label/{label_name}/values` [#post-prometheusapiv1labellabel_namevalues]

Read the values for a Prometheus label.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read the values for a Prometheus label.
curl -X POST "https://api.rawtree.com/prometheus/api/v1/label/job/values?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": []
}
```

GET `/prometheus/api/v1/series` [#get-prometheusapiv1series]

Read Prometheus series.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus series.
curl -X GET "https://api.rawtree.com/prometheus/api/v1/series?database=analytics&match%5B%5D=up" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": []
}
```

POST `/prometheus/api/v1/series` [#post-prometheusapiv1series]

Read Prometheus series.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus series.
curl -X POST "https://api.rawtree.com/prometheus/api/v1/series?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  --data-urlencode 'match[]=up'
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": []
}
```

GET `/prometheus/api/v1/metadata` [#get-prometheusapiv1metadata]

Read Prometheus metadata.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus metadata.
curl -X GET "https://api.rawtree.com/prometheus/api/v1/metadata?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": {}
}
```

GET `/prometheus/api/v1/status/buildinfo` [#get-prometheusapiv1statusbuildinfo]

Read Prometheus status/buildinfo.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Read Prometheus status/buildinfo.
curl -X GET "https://api.rawtree.com/prometheus/api/v1/status/buildinfo?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "status": "success",
  "data": {
    "version": "0.1.0",
    "revision": "rawtree",
    "branch": "rawtree",
    "buildUser": "rawtree",
    "buildDate": "",
    "goVersion": ""
  }
}
```

Remote write payload [#remote-write-payload]

Prometheus remote write uses a Snappy-compressed Protobuf `WriteRequest`.
Configure your Prometheus exporter with the [remote write guide](/docs/integrations/prometheus).
The file in the HTTP example is a captured exporter payload. JSON is not a remote write format.
A successful write returns `204` with no body. Unsupported or malformed payloads return an error.

POST `/prometheus/api/v1/write` [#post-prometheusapiv1write]

Write Prometheus samples.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Send a Snappy-compressed Prometheus WriteRequest from your exporter.
curl -X POST "https://api.rawtree.com/prometheus/api/v1/write?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/x-protobuf" \
  -H "Content-Encoding: snappy" \
  -H "X-Prometheus-Remote-Write-Version: 0.1.0" \
  --data-binary @write-request.snappy
```

Expected response: **HTTP 204**.

The response body is empty.