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

# Alerts

> Define and manage alerts. Alerts evaluate event metrics on a schedule and trigger notifications when configured thresholds are crossed.

## Schema introspection

Every command below with arguments supports two read-only flags for tooling and AI agents:

* `--show-file-schema`: print the JSON Schema for the full request object (the format `--filename` accepts).
* `--show-argument-schema <flag-name>`: print the JSON Schema for one argument's value. Pass the kebab flag name **without** the leading `--` (e.g. `project-id`, not `--project-id`).

Both write pure JSON to stdout and never call the API. They cannot be combined with any other command-specific flag.

## `list`

List alerts

List the alerts in a project. The project is identified by the `project_id` path parameter
alone; the `x-hh-project-id` header does not participate. Supports offset pagination, an
optional status filter, and sorting (defaults to most recently created first).

### Usage

```sh theme={null}
honeyhive alerts list [options]
```

### Options

| Flag           | Type   | Required | Description                                                                                                    |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------- |
| `--project-id` | string | yes      | The unique identifier of the project whose alerts are listed                                                   |
| `--limit`      | number | no       | Number of alerts to return per page                                                                            |
| `--page`       | number | no       | 1-indexed page number                                                                                          |
| `--sort-by`    | string | no       | Field to sort results by Allowed: `created_at`, `updated_at`, `name`, `status`, `frequency`, `last_triggered`. |
| `--sort-order` | string | no       | Sort order Allowed: `asc`, `desc`.                                                                             |
| `--status`     | string | no       | Only return alerts in this status Allowed: `ACTIVE`, `TRIGGERED`, `PAUSED`, `RESOLVED`.                        |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.

## `create`

Create an alert

Create an alert in a project. The project is identified by the `project_id` path parameter
alone; the `x-hh-project-id` header does not participate. The alert's `filters` and
`projections` (metrics) are mapped against the project's logged-event schema; if no schema
data matches them — e.g. no events have been logged to the project yet — the request fails
with a 400.

### Usage

```sh theme={null}
honeyhive alerts create [options]
```

### Options

| Flag                     | Type   | Required | Description                                                                                  |
| ------------------------ | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `--filters`              | json   | yes      | filters                                                                                      |
| `--frequency`            | string | yes      | frequency Allowed: `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`.                                   |
| `--name`                 | string | yes      | name                                                                                         |
| `--notification-details` | json   | yes      | notification\_details                                                                        |
| `--project-id`           | string | yes      | The unique identifier of the project the alert is created in                                 |
| `--projections`          | json   | yes      | projections                                                                                  |
| `--thresholds`           | json   | yes      | thresholds                                                                                   |
| `--aggregation`          | string | no       | aggregation Allowed: `AVERAGE`, `COUNT`, `SUM`, `MIN`, `MAX`, `P90`, `P95`, `P99`, `MEDIAN`. |
| `--alert-type`           | string | no       | alert\_type Allowed: `DRIFT`, `AGGREGATE`, `PER_EVENT`.                                      |
| `--description`          | string | no       | description                                                                                  |
| `--minimum-sample-size`  | number | no       | minimum\_sample\_size                                                                        |
| `--status`               | string | no       | status Allowed: `ACTIVE`, `TRIGGERED`, `PAUSED`, `RESOLVED`.                                 |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.

## `get`

Get an alert

Retrieve a single alert by id, including its thresholds, triggers, and notification
configuration. The alert's project is identified by the `project_id` path parameter alone;
the `x-hh-project-id` header does not participate.

### Usage

```sh theme={null}
honeyhive alerts get [options]
```

### Options

| Flag           | Type   | Required | Description                                               |
| -------------- | ------ | -------- | --------------------------------------------------------- |
| `--alert-id`   | string | yes      | The unique identifier of the alert to retrieve            |
| `--project-id` | string | yes      | The unique identifier of the project the alert belongs to |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.


## Related topics

- [Creating Alerts](/v2/monitoring/alerts/alerts.md)
- [Alerts Methods](/v2/control-plane-sdk-reference/typescript/ref/alerts/index.md)
- [Get an alert](/v2/control-plane-api-reference-autogen/alerts/get-an-alert.md)