Plural Telemetry
API reference · v0.1.0

Metrics HTTP API

Prometheus-compatible query and ingestion API. Configure path_prefix to prepend a common prefix to data routes. Generated from the OpenAPI 3.1 document shipped with the server.

Base URLs

Writers serve every /write route and readers serve every /read route. The operator creates a Service for each, named after the Metrics resource. Any writer accepts any write and forwards it to the owning shard, so plain round-robin load balancing is enough.

Authentication

Requests use HTTP basic auth. Each NamespaceAuthentication grants one username read or write on one namespace, with the password held in a Secret. Probes and self-metrics are unauthenticated.

Namespaces

Data is partitioned into tenant namespaces, and every data route carries one as /read/ns/{namespace} or /write/ns/{namespace}. A Prometheus data source pointed at http://metrics-reader.telemetry:8080/read/ns/default works unchanged.

Errors and backpressure

Errors use the Prometheus error envelope with a 4xx or 5xx status. When object storage falls behind, writers reject new batches with 429 and a Retry-After header; configure your agent to retry them.
Base URLs
writer
http://metrics-writer.telemetry:8080
reader
http://metrics-reader.telemetry:8080
Endpoints15
Error · 400
{
  "status": "error",
  "errorType": "bad_data",
  "error": "parse error: unexpected \"}\" in label matching"
}
Resource

query

PromQL evaluation with standard Prometheus response envelopes.

Instant query

GET/read/ns/{namespace}/api/v1/query
Evaluates a PromQL expression at a single timestamp, defaulting to now. Returns the standard Prometheus {status, data} envelope.

Path parameters

  • namespacestringrequired
    Configured tenant namespace

Query parameters

  • querystringrequired
    PromQL expression
  • timestring
    Evaluation timestamp: Unix seconds or RFC 3339

Responses

  • 200Prometheus instant-query responseapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
  • 400Invalid queryapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
  • 401Authentication required
  • 404Unknown namespace
  • 422Query failed during evaluationapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
Request
curl -G http://metrics-reader.telemetry:8080/read/ns/default/api/v1/query \
  -u reader:$PASSWORD \
  --data-urlencode 'query=sum by (job) (rate(http_requests_total{status=~"5.."}[5m]))'
Response · 200
{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "job": "api"
        },
        "value": [
          1791464400,
          "0.0213"
        ]
      }
    ]
  }
}

Instant query (form)

POST/read/ns/{namespace}/api/v1/query
Evaluates a PromQL expression at a single timestamp, defaulting to now. Returns the standard Prometheus {status, data} envelope.

Path parameters

  • namespacestringrequired
    Configured tenant namespace

Form fields

application/x-www-form-urlencoded
  • querystringrequired
    PromQL expression
  • timestring
    Evaluation timestamp: Unix seconds or RFC 3339

Responses

  • 200Prometheus instant-query responseapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
  • 400Invalid queryapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
  • 422Query failed during evaluationapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
Request
curl -X POST "http://metrics-reader.telemetry:8080/read/ns/default/api/v1/query" \
  -u reader:$PASSWORD \
  --data-urlencode 'query=sum by (job) (rate(http_requests_total{status=~"5.."}[5m]))'
Response · 200
{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "job": "api"
        },
        "value": [
          1791464400,
          "0.0213"
        ]
      }
    ]
  }
}

Range query

GET/read/ns/{namespace}/api/v1/query_range
Evaluates a PromQL expression from start to end every step. Returns a Prometheus matrix.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Query parameters

  • querystringrequired
    PromQL expression
  • startstringrequired
    Unix seconds or RFC 3339
  • endstringrequired
    Unix seconds or RFC 3339
  • stepstringrequired
    Seconds or a Prometheus duration such as 15s

Responses

  • 200Prometheus range-query responseapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
  • 400Invalid queryapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
  • 422Query failed during evaluationapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
Request
curl -G http://metrics-reader.telemetry:8080/read/ns/default/api/v1/query_range \
  -u reader:$PASSWORD \
  --data-urlencode 'query=sum by (job) (rate(http_requests_total{status=~"5.."}[5m]))' \
  --data-urlencode 'start=2026-10-08T12:00:00Z' \
  --data-urlencode 'end=2026-10-08T13:00:00Z' \
  --data-urlencode 'step=30s'
Response · 200
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "job": "api"
        },
        "values": [
          [
            1791460800,
            "0.0198"
          ],
          [
            1791460830,
            "0.0213"
          ]
        ]
      }
    ]
  }
}

Range query (form)

POST/read/ns/{namespace}/api/v1/query_range
Evaluates a PromQL expression from start to end every step. Returns a Prometheus matrix.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Form fields

application/x-www-form-urlencoded
  • querystringrequired
    PromQL expression
  • startstringrequired
    Unix seconds or RFC 3339
  • endstringrequired
    Unix seconds or RFC 3339
  • stepstringrequired
    Seconds or a Prometheus duration such as 15s

Responses

  • 200Prometheus range-query responseapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
  • 400Invalid queryapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
  • 422Query failed during evaluationapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
Request
curl -X POST "http://metrics-reader.telemetry:8080/read/ns/default/api/v1/query_range" \
  -u reader:$PASSWORD \
  --data-urlencode 'query=sum by (job) (rate(http_requests_total{status=~"5.."}[5m]))' \
  --data-urlencode 'start=2026-10-08T12:00:00Z' \
  --data-urlencode 'end=2026-10-08T13:00:00Z' \
  --data-urlencode 'step=30s'
Response · 200
{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "job": "api"
        },
        "values": [
          [
            1791460800,
            "0.0198"
          ],
          [
            1791460830,
            "0.0213"
          ]
        ]
      }
    ]
  }
}

Federate

GET/read/ns/{namespace}/federate
Prometheus federation endpoint. Returns the latest sample of each matching series in text exposition format.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Query parameters

  • match[]array of stringrequired
    Series selectors

Responses

  • 200Prometheus text expositiontext/plain
Request
curl -G http://metrics-reader.telemetry:8080/read/ns/default/federate \
  -u reader:$PASSWORD \
  --data-urlencode 'match[]=up{job="api"}'
Response · 200
# TYPE up untyped
up{instance="10.0.4.12:9100",job="api"} 1 1791464400000
Resource

metadata

Series, label, and metadata discovery.

List label values

GET/read/ns/{namespace}/api/v1/label/{name}/values
Returns the values of one label. Use __name__ to list metric names.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.
  • namestringrequired
    Label name

Query parameters

  • match[]array of string
    Series selector. Repeat to match the union of several selectors.
  • startstring
    Start of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.
  • endstring
    End of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.

Responses

  • 200Label valuesapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
Request
curl -G http://metrics-reader.telemetry:8080/read/ns/default/api/v1/label/job/values \
  -u reader:$PASSWORD \
  --data-urlencode 'start=2026-10-08T12:00:00Z' \
  --data-urlencode 'end=2026-10-08T13:00:00Z'
Response · 200
{
  "status": "success",
  "data": [
    "api",
    "gateway",
    "node-exporter"
  ]
}

List label names

GET/read/ns/{namespace}/api/v1/labels
Returns label names, optionally restricted to series matching match[] within a time range.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Query parameters

  • match[]array of string
    Series selector. Repeat to match the union of several selectors.
  • startstring
    Start of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.
  • endstring
    End of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.

Responses

  • 200Label namesapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
Request
curl -G http://metrics-reader.telemetry:8080/read/ns/default/api/v1/labels \
  -u reader:$PASSWORD \
  --data-urlencode 'start=2026-10-08T12:00:00Z' \
  --data-urlencode 'end=2026-10-08T13:00:00Z'
Response · 200
{
  "status": "success",
  "data": [
    "__name__",
    "instance",
    "job",
    "status"
  ]
}

Metric metadata

GET/read/ns/{namespace}/api/v1/metadata
Returns type, help, and unit metadata recorded from remote write and OTLP ingest.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Query parameters

  • metricstring
    Restrict metadata to one metric name.
  • limitinteger
    Maximum number of results to return.
    Minimum 0

Responses

  • 200Metric metadataapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
Request
curl -G http://metrics-reader.telemetry:8080/read/ns/default/api/v1/metadata \
  -u reader:$PASSWORD \
  --data-urlencode 'limit=10'
Response · 200
{
  "status": "success",
  "data": {
    "http_requests_total": [
      {
        "type": "counter",
        "help": "Total HTTP requests.",
        "unit": ""
      }
    ]
  }
}

Find series

GET/read/ns/{namespace}/api/v1/series
Returns the label sets of series matching at least one match[] selector.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Query parameters

  • match[]array of stringrequired
    Series selectors
  • startstring
    Start of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.
  • endstring
    End of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.

Responses

  • 200Matching seriesapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
Request
curl -G http://metrics-reader.telemetry:8080/read/ns/default/api/v1/series \
  -u reader:$PASSWORD \
  --data-urlencode 'match[]=up{job="api"}' \
  --data-urlencode 'start=2026-10-08T12:00:00Z' \
  --data-urlencode 'end=2026-10-08T13:00:00Z'
Response · 200
{
  "status": "success",
  "data": [
    {
      "__name__": "up",
      "job": "api",
      "instance": "10.0.4.12:9100"
    }
  ]
}

Find series (form)

POST/read/ns/{namespace}/api/v1/series
Returns the label sets of series matching at least one match[] selector.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Form fields

application/x-www-form-urlencoded
  • match[]array of stringrequired
    Series selectors
  • startstring
    Start of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.
  • endstring
    End of the range, inclusive. RFC 3339 timestamp or Unix seconds, optionally fractional.

Responses

  • 200Matching seriesapplication/json
    ›ApiEnvelope
    • dataobjectrequired
    • statusstringrequired
      Prometheus response status (success or error).
Request
curl -X POST "http://metrics-reader.telemetry:8080/read/ns/default/api/v1/series" \
  -u reader:$PASSWORD \
  --data-urlencode 'match[]=up{job="api"}' \
  --data-urlencode 'start=2026-10-08T12:00:00Z' \
  --data-urlencode 'end=2026-10-08T13:00:00Z'
Response · 200
{
  "status": "success",
  "data": [
    {
      "__name__": "up",
      "job": "api",
      "instance": "10.0.4.12:9100"
    }
  ]
}
Resource

ingest

Remote write and OTLP. Samples are routed per routing epoch to their storage shard.

Remote write

POST/write/ns/{namespace}/api/v1/write
Prometheus remote write 1.0 and 2.0 (Snappy-compressed protobuf), including native histograms. With stock Prometheus, set queue_config.retry_on_http_429: true so backpressure is retried.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Request body

application/x-protobuf
Snappy-compressed Prometheus remote-write request: prometheus.WriteRequest (1.0, default) or io.prometheus.write.v2.Request when the content type carries proto=io.prometheus.write.v2.Request. Both carry native histograms.

Raw payload in the content type sent. See the request example.

Responses

  • 204Write accepted; 2.0 requests also receive X-Prometheus-Remote-Write-{Samples,Histograms,Exemplars}-Written headers
  • 400Invalid remote-write requestapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
  • 415Unsupported remote-write protobuf messageapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
Request
curl -X POST "http://metrics-writer.telemetry:8080/write/ns/default/api/v1/write" \
  -u writer:$PASSWORD \
  -H 'Content-Type: application/x-protobuf' \
  -H 'Content-Encoding: snappy' \
  --data-binary @payload.pb

OTLP metrics

POST/write/ns/{namespace}/v1/metrics
OTLP/HTTP ExportMetricsServiceRequest as protobuf or JSON, optionally gzip-encoded. Exponential histograms are stored as native histograms.

Path parameters

  • namespacestringrequired
    Tenant namespace. A NamespaceAuthentication for this database must grant the caller access to it.

Request body

application/jsonapplication/x-protobuf
OTLP ExportMetricsServiceRequest as protobuf or OTLP/JSON, optionally with Content-Encoding: gzip.

Responses

  • 200OTLP metrics accepted
  • 400Invalid OTLP requestapplication/json
    ›ErrorEnvelope
    • errorstringrequired
    • error_typestring | null
    • statusstringrequired
Request
curl -X POST "http://metrics-writer.telemetry:8080/write/ns/default/v1/metrics" \
  -u writer:$PASSWORD \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
{
  "resourceMetrics": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "api"
            }
          }
        ]
      },
      "scopeMetrics": [
        {
          "metrics": [
            {
              "name": "http_requests_total",
              "sum": {
                "isMonotonic": true,
                "aggregationTemporality": 2,
                "dataPoints": [
                  {
                    "asInt": "1027",
                    "timeUnixNano": "1791464400000000000"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}
EOF
Resource

operations

Probes and self-monitoring.

Liveness

GET/-/healthy
Returns 200 while the process is running. Use it as the Kubernetes liveness probe; it is unprefixed and not namespace-scoped.

Responses

  • 200Process is healthy
Request
curl http://metrics-reader.telemetry:8080/-/healthy

Readiness

GET/-/ready
Returns 200 once every storage shard assigned to this pod is open, and 503 while shards are still being acquired or handed off. Use it as the readiness probe.

Responses

  • 200Server is ready
  • 503Assigned shards are not ready
Request
curl http://metrics-reader.telemetry:8080/-/ready

Self metrics

GET/metrics
Prometheus exposition of the server's own metrics: ingest, query, SlateDB, cache, and shard ownership.

Responses

  • 200Server metricstext/plain
Request
curl http://metrics-reader.telemetry:8080/metrics
Response · 200
# HELP telemetry_ingest_samples_total Samples accepted.
# TYPE telemetry_ingest_samples_total counter
telemetry_ingest_samples_total 1.0274e+07