# Metrics API

The Uptizm API has 10 endpoints on this resource, one section each.

## List a monitor's metrics

`GET /monitors/{monitor}/metrics`

The custom metrics defined on the monitor, in display order.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:read`
- Tag: Metrics
- operationId: `v1.monitors.metrics.index`

### Parameters

- `monitor` (path, string, required): The monitor ID

### Response 200

Content type: `application/json`.

- `data` (array of MonitorMetricResource, required)
  - `id` (string, required)
  - `monitor_id` (string, required)
  - `group_name` (string or null, required)
  - `label` (string, required)
  - `key` (string, required)
  - `type` (string, one of `"numeric"`, `"status"`, `"string"`, required)
  - `source` (string or null, one of `"json_path"`, `"regex"`, `"xpath"`, `"header"`, `"http_status"`, `null`, required)
  - `extraction_path` (string or null, required)
  - `unit` (string or null, one of `"bytes_auto"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`, `"duration_auto"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"percent"`, `"ratio"`, `"count"`, `"count_short"`, `"custom"`, `null`, required)
  - `threshold_direction` (string or null, one of `"high_bad"`, `"low_bad"`, `null`, required)
  - `warn_bound` (number or null, required)
  - `critical_bound` (number or null, required)
  - `ok_values` (array of any, required): The string values that band as ok for a string metric.
  - `warn_values` (array of any, required)
  - `critical_values` (array of any, required)
  - `unmatched_band` (string or null, one of `"ok"`, `"warn"`, `"critical"`, `null`, required)
  - `anomaly_enabled` (boolean, required)
  - `anomaly_direction` (string, one of `"high_bad"`, `"low_bad"`, `"both"`, required)
  - `anomaly_kind` (string, one of `"gauge"`, `"counter"`, `"count_per_period"`, required)
  - `anomaly_sensitivity` (string, one of `"low"`, `"medium"`, `"high"`, required)
  - `display_order` (integer, required)
  - `latest` (object or null)
    - `recorded_at` (string or null, required)
    - `numeric_value` (number or null, required)
    - `string_value` (string, required)
    - `status_value` (string or null, required)
    - `band` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Create a metric

`POST /monitors/{monitor}/metrics`

Defines a custom metric that extracts a value from every check response of the monitor (JSONPath, regex, XPath, a header or the status code), with optional thresholds.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:write`
- Tag: Metrics
- operationId: `v1.monitors.metrics.store`

### Parameters

- `monitor` (path, string, required): The monitor ID
- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `group_name` (string or null, max length 80)
- `label` (string, max length 120, required)
- `type` (MetricType: string, one of `"numeric"`, `"status"`, `"string"`, required): Classification of a custom monitor metric.
- `source` (MetricSource: string, one of `"json_path"`, `"regex"`, `"xpath"`, `"header"`, `"http_status"` or null)
- `extraction_path` (string or null, max length 500)
- `unit` (MetricUnit: string, one of `"bytes_auto"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`, `"duration_auto"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"percent"`, `"ratio"`, `"count"`, `"count_short"`, `"custom"` or null)
- `threshold_direction` (ThresholdDirection: string, one of `"high_bad"`, `"low_bad"` or null)
- `warn_bound` (number or null)
- `critical_bound` (number or null)
- `display_order` (integer or null, min 0)
- `anomaly_enabled` (boolean)
- `anomaly_direction` (MetricAnomalyDirection: string, one of `"high_bad"`, `"low_bad"`, `"both"`): Which side of a baseline counts as an anomaly: `high_bad`, `low_bad` or `both`.
- `anomaly_kind` (MetricKind: string, one of `"gauge"`, `"counter"`, `"count_per_period"`): What a numeric metric's readings measure, which decides how the sweep reads them.
- `anomaly_sensitivity` (AnomalySensitivity: string, one of `"low"`, `"medium"`, `"high"`): How far from its baseline a metric has to move before the sweep reports it.
- `ok_values` (array of string, min length 1, max length 120, max items 50)
- `warn_values` (array of string, min length 1, max length 120, max items 50)
- `critical_values` (array of string, min length 1, max length 120, max items 50)
- `unmatched_band` (MetricBand: string, one of `"ok"`, `"warn"`, `"critical"` or null)
- `key` (string, max length 40, required)

### Response 201

Content type: `application/json`.

- `data` (MonitorMetricResource, required)
  - `id` (string, required)
  - `monitor_id` (string, required)
  - `group_name` (string or null, required)
  - `label` (string, required)
  - `key` (string, required)
  - `type` (string, one of `"numeric"`, `"status"`, `"string"`, required)
  - `source` (string or null, one of `"json_path"`, `"regex"`, `"xpath"`, `"header"`, `"http_status"`, `null`, required)
  - `extraction_path` (string or null, required)
  - `unit` (string or null, one of `"bytes_auto"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`, `"duration_auto"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"percent"`, `"ratio"`, `"count"`, `"count_short"`, `"custom"`, `null`, required)
  - `threshold_direction` (string or null, one of `"high_bad"`, `"low_bad"`, `null`, required)
  - `warn_bound` (number or null, required)
  - `critical_bound` (number or null, required)
  - `ok_values` (array of any, required): The string values that band as ok for a string metric.
  - `warn_values` (array of any, required)
  - `critical_values` (array of any, required)
  - `unmatched_band` (string or null, one of `"ok"`, `"warn"`, `"critical"`, `null`, required)
  - `anomaly_enabled` (boolean, required)
  - `anomaly_direction` (string, one of `"high_bad"`, `"low_bad"`, `"both"`, required)
  - `anomaly_kind` (string, one of `"gauge"`, `"counter"`, `"count_per_period"`, required)
  - `anomaly_sensitivity` (string, one of `"low"`, `"medium"`, `"high"`, required)
  - `display_order` (integer, required)
  - `latest` (object or null)
    - `recorded_at` (string or null, required)
    - `numeric_value` (number or null, required)
    - `string_value` (string, required)
    - `status_value` (string or null, required)
    - `band` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Preview a metric rule

`POST /monitors/{monitor}/metrics/preview`

Runs a draft extraction rule against the monitor's newest archived response and returns the extracted value and the threshold band it would land in. Stores nothing.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/preview`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:write`
- Tag: Metrics
- operationId: `v1.monitors.metrics.preview`

### Parameters

- `monitor` (path, string, required): The monitor ID
- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `source` (MetricSource: string, one of `"json_path"`, `"regex"`, `"xpath"`, `"header"`, `"http_status"`, required): Extraction strategy used to pull a metric value out of a check response.
- `extraction_path` (string or null, max length 500)
- `type` (MetricType: string, one of `"numeric"`, `"status"`, `"string"`, required): Classification of a custom monitor metric.
- `sample_body` (string or null)
- `sample_headers` (array of string or null)
- `sample_status_code` (integer or null)
- `threshold_direction` (ThresholdDirection: string, one of `"high_bad"`, `"low_bad"` or null)
- `warn_bound` (number or null)
- `critical_bound` (number or null)
- `ok_values` (array of string, min length 1, max length 120, max items 50)
- `warn_values` (array of string, min length 1, max length 120, max items 50)
- `critical_values` (array of string, min length 1, max length 120, max items 50)
- `unmatched_band` (MetricBand: string, one of `"ok"`, `"warn"`, `"critical"` or null)

### Response 200

Content type: `application/json`.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Discover metrics with AI

`POST /monitors/{monitor}/metrics/discover`

Proposes metrics worth adding, read from the monitor's newest archived content. Stores nothing; create the ones you want with `POST /monitors/{monitor}/metrics`.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/discover`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:write`
- Tag: Metrics
- operationId: `v1.monitors.metrics.discover`

### Parameters

- `monitor` (path, string, required): The monitor ID
- `Idempotency-Key` (header, string): Any unique string per logical request.

### Response 200

Content type: `application/json`.

- `data` (object, required)
  - `suggested_metrics` (array, max items 2 or array, max items 2 or array of string, max items 0, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Reorder metrics

`PATCH /monitors/{monitor}/metrics/reorder`

Sets `display_order` for a set of the monitor's metrics.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/reorder`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:write`
- Tag: Metrics
- operationId: `v1.monitors.metrics.reorder`

### Parameters

- `monitor` (path, string, required): The monitor ID

### Request body

Content type: `application/json`.

- `order` (array of object, required)
  - `id` (string, required)
  - `display_order` (integer, min 0, required)

### Response 204

No body.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Update a metric

`PUT /monitors/{monitor}/metrics/{metric}`

Edits one metric definition; only the fields sent change.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/{metric}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:write`
- Tag: Metrics
- operationId: `v1.monitors.metrics.update`

### Parameters

- `monitor` (path, string, required): The monitor ID
- `metric` (path, string, required): The metric ID

### Request body

Content type: `application/json`.

- `group_name` (string or null, max length 80)
- `label` (string, max length 120)
- `type` (MetricType: string, one of `"numeric"`, `"status"`, `"string"`): Classification of a custom monitor metric.
- `source` (MetricSource: string, one of `"json_path"`, `"regex"`, `"xpath"`, `"header"`, `"http_status"` or null)
- `extraction_path` (string or null, max length 500)
- `unit` (MetricUnit: string, one of `"bytes_auto"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`, `"duration_auto"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"percent"`, `"ratio"`, `"count"`, `"count_short"`, `"custom"` or null)
- `threshold_direction` (ThresholdDirection: string, one of `"high_bad"`, `"low_bad"` or null)
- `warn_bound` (number or null)
- `critical_bound` (number or null)
- `display_order` (integer or null, min 0)
- `anomaly_enabled` (boolean)
- `anomaly_direction` (MetricAnomalyDirection: string, one of `"high_bad"`, `"low_bad"`, `"both"`): Which side of a baseline counts as an anomaly: `high_bad`, `low_bad` or `both`.
- `anomaly_kind` (MetricKind: string, one of `"gauge"`, `"counter"`, `"count_per_period"`): What a numeric metric's readings measure, which decides how the sweep reads them.
- `anomaly_sensitivity` (AnomalySensitivity: string, one of `"low"`, `"medium"`, `"high"`): How far from its baseline a metric has to move before the sweep reports it.
- `ok_values` (array of string, min length 1, max length 120, max items 50)
- `warn_values` (array of string, min length 1, max length 120, max items 50)
- `critical_values` (array of string, min length 1, max length 120, max items 50)
- `unmatched_band` (MetricBand: string, one of `"ok"`, `"warn"`, `"critical"` or null)
- `key` (string, max length 40)

### Response 200

Content type: `application/json`.

- `data` (MonitorMetricResource, required)
  - `id` (string, required)
  - `monitor_id` (string, required)
  - `group_name` (string or null, required)
  - `label` (string, required)
  - `key` (string, required)
  - `type` (string, one of `"numeric"`, `"status"`, `"string"`, required)
  - `source` (string or null, one of `"json_path"`, `"regex"`, `"xpath"`, `"header"`, `"http_status"`, `null`, required)
  - `extraction_path` (string or null, required)
  - `unit` (string or null, one of `"bytes_auto"`, `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"`, `"terabyte"`, `"duration_auto"`, `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"percent"`, `"ratio"`, `"count"`, `"count_short"`, `"custom"`, `null`, required)
  - `threshold_direction` (string or null, one of `"high_bad"`, `"low_bad"`, `null`, required)
  - `warn_bound` (number or null, required)
  - `critical_bound` (number or null, required)
  - `ok_values` (array of any, required): The string values that band as ok for a string metric.
  - `warn_values` (array of any, required)
  - `critical_values` (array of any, required)
  - `unmatched_band` (string or null, one of `"ok"`, `"warn"`, `"critical"`, `null`, required)
  - `anomaly_enabled` (boolean, required)
  - `anomaly_direction` (string, one of `"high_bad"`, `"low_bad"`, `"both"`, required)
  - `anomaly_kind` (string, one of `"gauge"`, `"counter"`, `"count_per_period"`, required)
  - `anomaly_sensitivity` (string, one of `"low"`, `"medium"`, `"high"`, required)
  - `display_order` (integer, required)
  - `latest` (object or null)
    - `recorded_at` (string or null, required)
    - `numeric_value` (number or null, required)
    - `string_value` (string, required)
    - `status_value` (string or null, required)
    - `band` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Delete a metric

`DELETE /monitors/{monitor}/metrics/{metric}`

Deletes the metric and its readings.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/{metric}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:write`
- Tag: Metrics
- operationId: `v1.monitors.metrics.destroy`

### Parameters

- `monitor` (path, string, required): The monitor ID
- `metric` (path, string, required): The metric ID

### Response 204

No body.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Get recent samples of every metric

`GET /monitors/{monitor}/metrics/series`

The most recent samples of every metric on the monitor in one response.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/series`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:read`
- Tag: Metrics
- operationId: `v1.monitors.metrics.batch_series`

### Parameters

- `monitor` (path, string, required): The monitor ID

### Response 200

Content type: `application/json`.

- `data` (string, required)
- `meta` (object, required)
  - `range` (string, required)
  - `limit` (any, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Get a metric series

`GET /monitors/{monitor}/metrics/{metric}/series`

One metric's readings over the requested window, oldest first, for charting. Beyond 24 hours a numeric metric comes back as bucket averages.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/{metric}/series`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:read`
- Tag: Metrics
- operationId: `v1.monitors.metrics.series`

### Parameters

- `monitor` (path, string, required): The monitor ID
- `metric` (path, string, required): The metric ID

### Response 200

Content type: `application/json`.

- `data` (array of object, required)
  - `recorded_at` (string, required)
  - `numeric_value` (number or null, required)
  - `string_value` (string or null, required)
  - `status_value` (string or null, required)
  - `band` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## List a metric's readings

`GET /monitors/{monitor}/metrics/{metric}/readings`

One metric's readings, newest first, cursor-paginated.

- URL: `https://api.uptizm.com/v1/monitors/{monitor}/metrics/{metric}/readings`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `metrics:read`
- Tag: Metrics
- operationId: `v1.monitors.metrics.readings`

### Parameters

- `monitor` (path, string, required): The monitor ID
- `metric` (path, string, required): The metric ID
- `per_page` (query, integer, min 1, max 200): Page size, clamped to 1 and the endpoint's maximum (200 on most lists).
- `cursor` (query, string): The `meta.next_cursor` of the previous page.

### Response 200

Content type: `application/json`.

- `data` (array of MonitorMetricValueResource, required)
  - `id` (string, required)
  - `recorded_at` (string, required)
  - `numeric_value` (number or null, required)
  - `string_value` (string or null, required)
  - `status_value` (string or null, one of `"up"`, `"down"`, `"degraded"`, `"paused"`, `"maintenance"`, `null`, required)
  - `band` (string or null, one of `"ok"`, `"warn"`, `"critical"`, `null`, required)
- `links` (object, required)
  - `first` (string or null, required)
  - `last` (string or null, required)
  - `prev` (string or null, required)
  - `next` (string or null, required)
- `meta` (object, required)
  - `path` (string or null, required): Base path for paginator generated URLs.
  - `per_page` (integer, min 0, required): Number of items shown per page.
  - `next_cursor` (string or null, required): The "cursor" that points to the next set of items.
  - `prev_cursor` (string or null, required): The "cursor" that points to the previous set of items.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md