Skip to main content

Label Exploration

The labels, label values, and series endpoints show what exists in your tenant namespace. Use them when building dashboards or chasing down cardinality.

Required headers

All requests need both headers:

Authorization: Bearer <token>
X-Scope-OrgID: <tenant-id>

List all label names​

Returns every label key present across all series in your namespace.

curl "https://euw1-01.m.xscalerlabs.com/api/v1/labels" \
  -H "Authorization: Bearer <token>" \
  -H "X-Scope-OrgID: <tenant-id>"

Response:

{
  "status": "success",
  "data": ["__name__", "job", "instance", "method", "route", "status"]
}

List values for a specific label​

Returns all values for a given label key.

curl "https://euw1-01.m.xscalerlabs.com/api/v1/label/job/values" \
  -H "Authorization: Bearer <token>" \
  -H "X-Scope-OrgID: <tenant-id>"

Response:

{
  "status": "success",
  "data": ["api-server", "worker", "scheduler"]
}

Replace job in the URL path with any label name returned by the labels endpoint.

Find series matching a selector​

Use POST /series with a match[] selector to find all time series that match a given label set.

curl -X POST "https://euw1-01.m.xscalerlabs.com/api/v1/series" \
  -H "Authorization: Bearer <token>" \
  -H "X-Scope-OrgID: <tenant-id>" \
  --data-urlencode 'match[]=http_requests_total{job="api-server"}'

Response:

{
  "status": "success",
  "data": [
    {
      "__name__": "http_requests_total",
      "job": "api-server",
      "method": "GET",
      "status": "200"
    },
    {
      "__name__": "http_requests_total",
      "job": "api-server",
      "method": "POST",
      "status": "201"
    }
  ]
}

Limit results by time range​

Both /labels and /series accept optional start and end parameters to restrict results to a time range:

curl "https://euw1-01.m.xscalerlabs.com/api/v1/labels" \
  -H "Authorization: Bearer <token>" \
  -H "X-Scope-OrgID: <tenant-id>" \
  --data-urlencode 'start=2024-01-01T00:00:00Z' \
  --data-urlencode 'end=2024-01-02T00:00:00Z'

Find high-cardinality metrics​

Too many unique label value combinations slow queries down. This query finds the top offenders:

curl "https://euw1-01.m.xscalerlabs.com/api/v1/query" \
  -H "Authorization: Bearer <token>" \
  -H "X-Scope-OrgID: <tenant-id>" \
  --data-urlencode 'query=topk(10, count by (__name__)({__name__=~".+"}))'

This returns the 10 metric names with the most active time series. When one stands out, check which labels it carries and drop the values you do not need.