> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a metric



## OpenAPI

````yaml api-reference/openapi.json GET /metrics/{id}
openapi: 3.1.0
info:
  title: Observer API
  version: 1.2.0
  description: >-
    Public API for Observer: read services, metrics, SLOs and SLA statements;
    manage incidents, maintenance windows, manual metric status, config as code
    and Observer Agents. Bearer-auth via API keys (obs_pub_…), scoped per key.
    RFC 7807 problem-detail errors. Cursor pagination. Rate limits are per
    organization. Every date-time value is RFC 3339 in UTC with millisecond
    precision (`2026-01-31T12:00:00.000Z`).
servers:
  - url: https://use.observer/api/v1
security:
  - bearerAuth: []
paths:
  /metrics/{id}:
    get:
      tags:
        - metrics
      summary: Get metric by id or key
      operationId: getMetric
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            The metric's id, or its key in config documents (its config_key, or
            the key config export gives one made in the console).
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricDetail'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Daily-Limit:
              $ref: '#/components/headers/X-RateLimit-Daily-Limit'
            X-RateLimit-Daily-Remaining:
              $ref: '#/components/headers/X-RateLimit-Daily-Remaining'
            X-RateLimit-Daily-Reset:
              $ref: '#/components/headers/X-RateLimit-Daily-Reset'
        '401':
          description: >-
            `unauthenticated`: no bearer token was sent, or the key is invalid
            or revoked. `detail` distinguishes the two.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: >-
            `forbidden`: the key does not carry the scope this endpoint
            requires. `plan_does_not_permit_api`: the organization's plan does
            not include the public API.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: >-
            `not_found`: no metric with that id is available to this key. One
            owned by another organization, or an id that is not a valid UUID,
            returns the same response, so a 404 does not confirm that the id is
            unused.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: >-
            `rate_limited`: the organization's per-minute or daily request limit
            is used up (`limit.window` says which). Limits are per organization,
            shared by every key. The response carries `Retry-After` and
            `retry_after`, in seconds.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Daily-Limit:
              $ref: '#/components/headers/X-RateLimit-Daily-Limit'
            X-RateLimit-Daily-Remaining:
              $ref: '#/components/headers/X-RateLimit-Daily-Remaining'
            X-RateLimit-Daily-Reset:
              $ref: '#/components/headers/X-RateLimit-Daily-Reset'
        '500':
          description: '`internal_error`: an unhandled server error. Safe to retry.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth:
            - read:metrics
components:
  schemas:
    MetricDetail:
      allOf:
        - type: object
          required:
            - id
            - title
            - created_at
          properties:
            id:
              type: string
              format: uuid
            title:
              type: string
            description:
              type: string
            query:
              type: string
            source_type:
              type: string
              description: >-
                What produces the metric's samples: an agent probe type (http,
                prometheus, ...), manual, or heartbeat (cloud-evaluated pings,
                see /metrics/{id}/heartbeat).
            created_at:
              type: string
              format: date-time
            current_status:
              type:
                - string
                - 'null'
              enum:
                - healthy
                - degraded
                - unhealthy
                - no_data
                - unknown
                - null
            current_value:
              type:
                - string
                - number
                - 'null'
              description: >-
                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:
              type:
                - string
                - 'null'
              format: date-time
            unit:
              type:
                - string
                - 'null'
              description: >-
                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:
              type:
                - string
                - 'null'
              description: >-
                What the value is, in words (e.g. "response time in
                milliseconds").
            pending_status:
              type:
                - string
                - 'null'
              enum:
                - healthy
                - degraded
                - unhealthy
                - no_data
                - null
              description: >-
                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.
            pending_since:
              type:
                - string
                - 'null'
              format: date-time
              description: When the pending status was first seen.
            reason:
              type:
                - string
                - 'null'
              description: >-
                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:
              type:
                - string
                - 'null'
              description: >-
                Short human description of `reason` (null when there is nothing
                to explain).
            reason_hint:
              type:
                - string
                - 'null'
              description: One sentence on what usually causes `reason` and how to fix it.
            agent_id:
              type:
                - string
                - 'null'
              format: uuid
              description: >-
                The Observer Agent that runs this metric (null for heartbeat,
                manual and unassigned metrics). See /agents/{id}.
            config_key:
              type:
                - string
                - 'null'
              description: >-
                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:
              type: string
              enum:
                - config
                - console
              description: >-
                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.
            suspended:
              type: boolean
              description: >-
                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:
              type:
                - string
                - 'null'
              format: date-time
              description: When the suspension started.
            stale:
              type: boolean
              description: >-
                The newest sample is older than min(3x the push interval, 15
                minutes): the agent has gone quiet, so current_status is frozen.
        - type: object
          properties:
            healthy_operation:
              type: string
              enum:
                - over
                - under
                - equal
            healthy_value:
              type:
                - string
                - number
            unhealthy_operation:
              type: string
              enum:
                - over
                - under
                - equal
            unhealthy_value:
              type:
                - string
                - number
            dwell_seconds_to_breach:
              type: integer
              description: >-
                Seconds a worse status must hold before the metric flips. 0
                flips on the next confirming sample.
            dwell_seconds_to_recover:
              type: integer
              description: >-
                Seconds an improving status must hold before the metric flips.
                Also applies to transitions involving no_data.
            interval:
              type: integer
            interval_agent_push:
              type: integer
              description: Push interval in whole minutes.
            no_data_treatment:
              type: string
              enum:
                - no_data
                - healthy
                - degraded
                - unhealthy
              description: >-
                How a no_data sample counts for this metric (config documents
                and PUT /metrics/{key} set it).
            updated_at:
              type: string
              format: date-time
            key:
              type: string
              description: >-
                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:
              type: object
              description: >-
                The probe configuration as stored, with the probe type's
                defaults filled in. Secrets are env var names (…_ref), never
                values.
            thresholds:
              type: object
              description: >-
                The stored thresholds in config-document shape (the same values
                as the healthy_* and unhealthy_* fields). Derived for heartbeat
                and alert metrics.
              properties:
                healthy_operation:
                  type:
                    - string
                    - 'null'
                  enum:
                    - over
                    - under
                    - equal
                    - null
                healthy_value:
                  type:
                    - number
                    - string
                    - 'null'
                unhealthy_operation:
                  type:
                    - string
                    - 'null'
                  enum:
                    - over
                    - under
                    - equal
                    - null
                unhealthy_value:
                  type:
                    - number
                    - string
                    - 'null'
    Problem:
      type: object
      required:
        - type
        - title
        - status
      example:
        type: https://docs.use.observer/api/getting-started/errors#forbidden
        title: forbidden
        status: 403
        detail: 'missing scope: write:incidents'
      properties:
        type:
          type: string
          format: uri
          description: Errors reference URI with the title token as the fragment.
          example: https://docs.use.observer/api/getting-started/errors#forbidden
        title:
          type: string
          description: Stable error token. Branch on this, not on detail.
        status:
          type: integer
        detail:
          type: string
          description: Human-readable explanation. Wording may change.
        retry_after:
          type: integer
          description: >-
            429 only: seconds until the exhausted window resets (mirrors
            Retry-After).
        limit:
          type: object
          description: '429 only: which organization limit was hit.'
          properties:
            scope:
              type: string
              enum:
                - organization
            window:
              type: string
              enum:
                - minute
                - day
            max:
              type: integer
            plan:
              type: string
        errors:
          type: array
          description: >-
            Validation failures (config_invalid, invalid_customer_targeting):
            one entry per problem.
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
        warnings:
          type: array
          description: >-
            config_invalid only: the same non-fatal warnings a successful apply
            returns.
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
        unknown_customers:
          type: array
          description: >-
            unknown_customers only: the submitted values that matched no
            customer in your organization.
          items:
            type: string
        unknown_services:
          type: array
          description: >-
            unknown_services only: the submitted `affected_services` values that
            matched no service in your organization.
          items: {}
        referenced_by:
          type: object
          description: >-
            in_use only: what depends on the object (slos, pages: lists of { id,
            config_key, name }; subscribers: a count).
        quota:
          type: object
          description: >-
            quota_exceeded / feature_locked on a create, item_suspended_plan on
            a write to a suspended item: the plan limit involved.
          properties:
            capability:
              type: string
            used:
              type:
                - integer
                - 'null'
            cap:
              type:
                - integer
                - 'null'
            plan:
              type:
                - string
                - 'null'
        upgrade:
          type: object
          description: >-
            Plan-limit problems only, when a higher plan lifts the limit: the
            smallest such plan and the pricing page.
          properties:
            plan:
              type: string
            label:
              type: string
            url:
              type: string
              format: uri
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per minute for the organization.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Seconds until the per-minute window resets.
      schema:
        type: integer
    X-RateLimit-Daily-Limit:
      description: Requests allowed per UTC day for the organization.
      schema:
        type: integer
    X-RateLimit-Daily-Remaining:
      description: Requests left today (UTC).
      schema:
        type: integer
    X-RateLimit-Daily-Reset:
      description: Seconds until the daily quota resets (UTC midnight).
      schema:
        type: integer
    Retry-After:
      description: '429 only: seconds to wait before retrying.'
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: obs_pub_
      description: >-
        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.