Metrics API (Authenticated)

Last updated: 2026-07-17

The Metrics API lets you read live metric values and update them from your own scripts, CI pipelines, or backend services — for example, incrementing a “deploys today” counter from a deploy hook, or setting “requests served” from a periodic job.

Metrics are display-only values. They don’t affect operational status, incidents, or uptime, and updating one never notifies subscribers.

Base URL

https://statuspage.me/user/api/v1

Authentication

Include an API key with the required scope as:

Authorization: Bearer spk_...

See API Console for key creation.

Creating, renaming, re-iconing, or deleting metrics is only available from the Metrics page in the dashboard — see Live Metrics.

Endpoints

List Metrics

GET /metrics?status_page_id=:status_page_id

Returns all metrics for a status page you can view, in display order.

Example Request

curl "https://statuspage.me/user/api/v1/metrics?status_page_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer spk_..."

Example Response

{
  "data": [
    {
      "id": "6f1c9b2a-6b1e-4c8e-9a3d-1f2e3d4c5b6a",
      "status_page_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Requests served today",
      "value": "128432",
      "unit_suffix": "req",
      "icon": "graph-up-arrow",
      "position": 0,
      "source_kind": "stored",
      "created_at": "2026-07-01T09:00:00Z",
      "updated_at": "2026-07-17T08:12:00Z"
    }
  ]
}

Get a Single Metric

GET /metrics/:id

Example Request

curl "https://statuspage.me/user/api/v1/metrics/6f1c9b2a-6b1e-4c8e-9a3d-1f2e3d4c5b6a" \
  -H "Authorization: Bearer spk_..."

Returns 404 if the metric doesn’t exist or you don’t have access to its status page.

Update a Metric’s Value

POST /metrics/:id/value

Atomically changes a metric’s stored value. Requires the status-pages:write scope.

Body

reset always sets the value to 0.

Example: Set

curl -X POST "https://statuspage.me/user/api/v1/metrics/6f1c9b2a-6b1e-4c8e-9a3d-1f2e3d4c5b6a/value" \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{"operation": "set", "value": "128500"}'

Example: Increment

curl -X POST "https://statuspage.me/user/api/v1/metrics/6f1c9b2a-6b1e-4c8e-9a3d-1f2e3d4c5b6a/value" \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{"operation": "increment", "value": "1"}'

Example: Reset

curl -X POST "https://statuspage.me/user/api/v1/metrics/6f1c9b2a-6b1e-4c8e-9a3d-1f2e3d4c5b6a/value" \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{"operation": "reset"}'

Response

{
  "data": {
    "id": "6f1c9b2a-6b1e-4c8e-9a3d-1f2e3d4c5b6a",
    "status_page_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Requests served today",
    "value": "128500",
    "unit_suffix": "req",
    "icon": "graph-up-arrow",
    "position": 0,
    "source_kind": "stored",
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-17T09:03:00Z"
  }
}

Value Format

• Values are accepted and returned as strings, not numbers, to preserve exact decimal precision (no floating-point rounding)
• Up to 3 fractional digits are supported
• Trailing zeros are trimmed in responses (12.500 becomes 12.5)

Idempotency Notes

increment and decrement updates are applied atomically at the database level, so concurrent requests won’t race each other. However, this endpoint does not provide durable idempotency keys — if a client sees a network error or timeout, it can’t safely tell whether the update actually applied before retrying. Avoid blind retries of increment/decrement calls after an unknown network outcome; prefer set with a value you compute independently when exact accuracy matters.

Error Responses

Related

• Live Metrics — create and manage metrics in the dashboard
• Authenticated REST API Overview
• API Console
• Status Pages API (Authenticated)