Skip to main content
GET
Get metric by id or key

Authorizations

Authorization
string
header
required

An organization API key (obs_pub_…) sent as Authorization: Bearer <key>. Each key carries scopes; an endpoint lists the scope it needs. read:change_events is reserved: keys can carry it, but no endpoint needs it yet.

Scopes

read:metrics

Path Parameters

id
string
required

The metric's id, or its key in config documents (its config_key, or the key config export gives one made in the console).

Response

ok

id
string<uuid>
required
title
string
required
created_at
string<date-time>
required
description
string
query
string
source_type
string

What produces the metric's samples: an agent probe type (http, prometheus, ...), manual, or heartbeat (cloud-evaluated pings, see /metrics/{id}/heartbeat).

current_status
enum<string> | null
Available options:
healthy,
degraded,
unhealthy,
no_data,
unknown,
null
current_value

The latest value, in unit. Always null while current_status is no_data (a failed sample has no value); a recovering metric shows its new status in pending_status.

current_timestamp
string<date-time> | null
unit
string | null

Unit of current_value and of the history values: ms, %, days, s, B/s; null for a bare number (a query result in whatever unit the query returns, or a 1/0 state). Follows from source_type and source_config:

  • prometheus: Value: scalar result of the PromQL query, as returned by the query; Observer does not rescale it.
  • http: Value: ms: response time in milliseconds. With json_path set: the number extracted from the JSON response at json_path (booleans read as 1/0); unit as in the response.
  • tcp: Value: ms: TCP connect time in milliseconds.
  • dns: Value: ms: DNS resolve time in milliseconds.
  • icmp: Value by interpretation: interpretation=latency (default) → ms: average round-trip time in milliseconds; interpretation=packet_loss → %: percentage of pings lost, 0 to 100; interpretation=reachability → 1 when any ping returned, 0 when none did.
  • tls_cert: Value: days: days until the certificate expires.
  • grpc: Value by interpretation: interpretation=health_state (default) → 1 when the health check reports SERVING, 0 when NOT_SERVING; interpretation=latency → ms: health check round-trip time in milliseconds.
  • websocket: Value by interpretation: interpretation=handshake_latency (default) → ms: handshake time in milliseconds; interpretation=round_trip_latency → ms: message round-trip time in milliseconds; interpretation=connection_success → 1 when the socket opened, 0 when it did not.
  • mtls_http: Value: ms: response time in milliseconds (deprecated alias of http). With json_path set: the number extracted from the JSON response at json_path (booleans read as 1/0); unit as in the response.
  • database: Value: scalar returned by the read-only query (one row, one column), as returned by the query; Observer does not rescale it.
  • otlp: Value: aggregated value of the pushed OTLP data points, in the instrument's own unit.
  • cloudwatch: Value: latest CloudWatch datapoint for the chosen statistic, in the metric's CloudWatch unit.
  • custom: Value: number returned by the registered probe function, in whatever unit it uses.
  • loki: Value: scalar result of the LogQL aggregation, as returned by the query; Observer does not rescale it.
  • elasticsearch: Value: value of the named aggregation, as returned by the query; Observer does not rescale it.
  • host: Value by metric: metric=cpu (default) → %: CPU utilisation percentage, 0 to 100; metric=memory → %: used memory percentage, 0 to 100; metric=filesystem → %: used disk space percentage of the mountpoint, 0 to 100; metric=network → B/s: network throughput in bytes per second (received + sent); metric=load → 1-minute load average divided by the CPU count.
  • datadog: Value: scalar result of the Datadog metrics query over the window, as returned by the query; Observer does not rescale it.
  • gcp_monitoring: Value: scalar result of the PromQL query against Cloud Monitoring, as returned by the query; Observer does not rescale it.
  • azure_monitor: Value: latest Azure Monitor data point for the chosen aggregation, in the metric's Azure unit.
  • manual: Value: no measured value; the status is set by hand or by an open incident.
  • heartbeat: Value: s: seconds since the last successful ping.
  • alert: Value: worst firing alert as a score: 0 none, 1 degraded, 2 unhealthy.
value_description
string | null

What the value is, in words (e.g. "response time in milliseconds").

pending_status
enum<string> | null

The status the metric is changing to while its dwell window runs (null when nothing is pending). current_status no_data with pending_status healthy means the probe is answering again and the metric is recovering: it flips once dwell_seconds_to_recover has held.

Available options:
healthy,
degraded,
unhealthy,
no_data,
null
pending_since
string<date-time> | null

When the pending status was first seen.

reason
string | null

Why the latest sample has no value or failed: the agent's reason code (e.g. ECONNREFUSED, mtls_ref_missing). Stable; branch on this.

reason_label
string | null

Short human description of reason (null when there is nothing to explain).

reason_hint
string | null

One sentence on what usually causes reason and how to fix it.

agent_id
string<uuid> | null

The Observer Agent that runs this metric (null for heartbeat, manual and unassigned metrics). See /agents/{id}.

config_key
string | null

The metric's key in config documents (null for one made in the console and never applied from config). Per-key DELETE takes this.

managed_by
enum<string>

config: owned by config apply (prune and per-key delete may remove it). console: made in the console; config apply adopts it when a document names it.

Available options:
config,
console
suspended
boolean

true while the metric is suspended because the organization is over its plan's limit (after a 7-day grace). Nothing is deleted; it is read-only until the person chooses it as active in Billing or upgrades. Writes return 403 item_suspended_plan.

suspended_at
string<date-time> | null

When the suspension started.

stale
boolean

The newest sample is older than min(3x the push interval, 15 minutes): the agent has gone quiet, so current_status is frozen.

healthy_operation
enum<string>
Available options:
over,
under,
equal
healthy_value
unhealthy_operation
enum<string>
Available options:
over,
under,
equal
unhealthy_value
dwell_seconds_to_breach
integer

Seconds a worse status must hold before the metric flips. 0 flips on the next confirming sample.

dwell_seconds_to_recover
integer

Seconds an improving status must hold before the metric flips. Also applies to transitions involving no_data.

interval
integer
interval_agent_push
integer

Push interval in whole minutes.

no_data_treatment
enum<string>

How a no_data sample counts for this metric (config documents and PUT /metrics/{key} set it).

Available options:
no_data,
healthy,
degraded,
unhealthy
updated_at
string<date-time>
key
string

The metric's key in config documents: its config_key, or the key config export gives a console metric. PUT /metrics/{key} takes it.

source_config
object

The probe configuration as stored, with the probe type's defaults filled in. Secrets are env var names (…_ref), never values.

thresholds
object

The stored thresholds in config-document shape (the same values as the healthy_* and unhealthy_* fields). Derived for heartbeat and alert metrics.