# Alerts

## Alert Model

### Fields

- **`object`** `"alert"`

- **`id`** `string`

   Unique identifier, prefixed with `alr_`.

- **`slug`** `string`

   URL-safe identifier for the alert.

- **`team_id`** `string`

- **`project_id`** `string`

- **`metric_id`** `string`

   The metric the monitor was watching.

- **`metric_name`** `string | null`

- **`monitor_id`** `string`

   The monitor that raised the alert.

- **`monitor_name`** `string | null`

- **`created_at`** [`ISODateString`](/api/alerts#iso-date-string)

   When the condition first held. The start of the firing period.

- **`ended_at`** [`ISODateString | null`](/api/alerts#iso-date-string)

   When the condition stopped holding. Null while the alert is still firing.

- **`series_hash`** `string`

   Identifies which series of the metric fired, when the monitor watches series separately.

- **`series_label`** `string | null`

- **`trigger_value`** `number`

   The metric value at the moment the alert opened.

- **`threshold_value`** `number`

   The value the metric had to cross for the monitor to fire.

- **`condition_description`** `string`

   The condition in words, for example `above 500 for 10 minutes`.

### Referenced Types

#### ISODateString

`ISODateString`

An ISO 8601 date-time string returned at the JSON API boundary.

## List Alerts

### Endpoint

List the alerts a metric's monitors have raised.

```http
GET /v1/projects/:project_id/metrics/:metric_id/alerts
```

**Scope:** `alerts:read`

### Path Parameters

- **`project_id`** `string` -- **Required**
  Unique identifier of the project.

- **`metric_id`** `string` -- **Required**
  Unique identifier of the metric.

### Query Parameters

- **`order_by`** `string`
  Field the results are sorted by. Alerts sort by when their period opened. Optional. Defaults to `"created_at"`. Allowed values: `"created_at"`.

- **`metric_id`** `string`
  Return only alerts raised on this metric. Optional.

- **`monitor_id`** `string`
  Return only alerts raised by this monitor. Optional.

- **`is_open`** `string`
  Set true for periods still firing, false for periods that have ended. Optional. Allowed values: `"true"`, `"false"`, `"1"`, `"0"`.

- **`time_range`** [`AnalyticsTimeRange`](/api/metrics#analytics-time-range)
  Window to search, relative to now. Ignored when start_at and end_at are sent. Optional.

- **`timezone`** `string`
  IANA timezone the time range is anchored to. Defaults to UTC. Optional.

- **`page_id`** `string`
  Resolve the time range from this page's setting instead of the metric's. Optional.

- **`start_at`** [`ISODateString`](/api/alerts#iso-date-string)
  Start of the window to search, as an ISO 8601 value. Optional.

- **`end_at`** [`ISODateString`](/api/alerts#iso-date-string)
  End of the window to search, as an ISO 8601 value. Optional.

- **`limit`** `number`
  Maximum number of items to return. Optional. Defaults to `25`. Minimum: `1`. Maximum: `200`.

- **`after`** `string`
  Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page. Optional.

- **`before`** `string`
  Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page. Optional.

- **`sort`** `string`
  Sort direction for the result set. Optional. Defaults to `"desc"`. Allowed values: `"asc"`, `"desc"`.

### Response

```ts
{
  message: string;
  data: Alert[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}
```

### Comments

- An alert is a firing PERIOD, not a single notification. `created_at` is when the condition started holding and `ended_at` is when it stopped, so one incident is one row for its whole duration.
- Results cover a time window. Send `start_at` and `end_at`, or a `time_range`; with neither, the metric's own configured chart range is used.
- An alert is returned when its period OVERLAPS the window, so a period that opened before the window and is still firing is included.
- Use `is_open=true` to see only what is currently firing.
- `before` and `after` are mutually exclusive. Send one or neither.
- `timezone` must be a valid IANA timezone name, or `UTC`.
- `after` and `before` are mutually exclusive.

## Retrieve Alert

### Endpoint

Retrieve a single alert.

```http
GET /v1/projects/:project_id/alerts/:alert_id
```

**Scope:** `alerts:read`

### Path Parameters

- **`project_id`** `string` -- **Required**
  Unique identifier of the project.

- **`alert_id`** `string` -- **Required**
  Unique identifier of the alert.

### Response

Alert retrieved

```ts
{
  message: string;
  data: Alert;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}
```

### Comments

- A null `ended_at` means the condition still holds and the period is still open.