---
title: "Get a metric alarm"
method: GET
path: "/orgs/{org_id}/alarms/{alarm_id}"
tags: ["alarms"]
---

# Get a metric alarm

`GET /orgs/{org_id}/alarms/{alarm_id}`

## Request

- Base URL: `https://api.timbal.ai`
- URL: `https://api.timbal.ai/orgs/{org_id}/alarms/{alarm_id}`
- Auth: HTTP bearer

One alarm's configuration, current state and linked channels.

Same shape as an entry in `GET /orgs/{org_id}/alarms`, for refreshing a detail view without refetching the whole list.

Needs `alarms.read` for an org-level alarm, or `projects.alarms.read` on the owning project for a project alarm.

## Path parameters

- `org_id` string, required
- `alarm_id` string, required

## Response `200`

The alarm

- AlarmOut
  - `channels` NotificationChannelOut[], required
    - `config` object, required
    - `id` integer, required
    - `name` string, nullable
    - `type` 'email' | 'slack', required
  - `clear_threshold` number, double, nullable: Set when this alarm uses hysteresis; see [`CreateAlarmReq`].
  - `comparison` 'gt' | 'gte' | 'lt' | 'lte', required
  - `datapoints_to_alarm` integer, required
  - `denominator_metric_name` string, nullable: Set when this is a ratio alarm; see [`CreateAlarmReq`].
  - `dims` AlarmDims, required: Metric dimension filters. Omitted = aggregate across that dimension. Not `Copy` since `label` is owned.
    - `deployment_id` string, nullable
    - `label` string, nullable: `Metrics.label` — the span name behind a trace-derived metric. Scopes the alarm to one tool/step instead of the sum over every span the filter matched.
    - `project_env_id` string, nullable
    - `project_id` string, nullable
    - `workforce_id` string, nullable: Agent / workflow app (`OrgsApps.id`).
  - `enabled` boolean, required
  - `evaluation_periods` integer, required
  - `id` integer, required
  - `metric_name` string, required
  - `min_sample_count` integer, required
  - `missing_data` 'not_breaching' | 'breaching' | 'insufficient' | 'ignore', required
  - `name` string, required
  - `period_seconds` integer, required
  - `project_id` integer, nullable: Project this alarm belongs to; omitted for org-level alarms.
  - `stat` string, required: Aggregation applied to each evaluation period. Percentiles run from p0.1 to p99.9 in tenths; equivalent spellings such as p95.0 are accepted and returned canonically as p95, while a finer value such as p95.05 is rejected rather than rounded. They are exact rather than interpolated from bins, so they are only available on app.run.duration_ms and cannot be used with denominator_metric_name.
  - `state` 'ok' | 'alarm' | 'insufficient_data', required
  - `state_changed_at` string, date-time, nullable
  - `threshold` number, double, required

## Other responses

- `403`: Forbidden
- `404`: Alarm not found for this org

## Changes

- **2026-07-28** `dd7e398ce0d3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/changes/orgs/:org_id/alarms/:alarm_id/get.md)

---

[API](https://skmtc.dev/timbal-ai/apis/timbal-platform-api.md) - [All operations](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/revisions/dd7e398ce0d3?raw)