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.

:::warning 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.