# Create an uptime check

Have the platform request a URL on a schedule, and mail you or call a webhook when it goes down and when it is back.

Replace _https://shop.example.com/health_ with the URL to check. For how a check decides it is
down, see [How uptime checks work](how-uptime-checks-work.md).

## Prerequisites

- Permission for `monitoring:CreateCheck` on `rn:ews::<organization id>:monitoring:*`. Without it,
  the console's **Create check** is unavailable, with the note "Creating a check needs
  monitoring:CreateCheck. Ask an administrator."
- In the console, also `monitoring:DescribeChecks` to open **Uptime** (without it the page shows an
  access-denied notice).
- Room in the **Uptime checks** quota (see [Quotas](quotas.md)).

## Create the check

**Console**
1. Open **Monitoring**, then **Uptime**, and choose **Create check**.
2. For **Name**, enter Shop.
3. For **URL**, enter https://shop.example.com/health.
4. For **Type**, keep **HTTP(S)**, or choose **Keyword** to also require a text in the body. For
   **Keyword**, enter the text, and for **In the body, it**, choose **must appear** or
   **must not appear**.
5. (Optional) Change **Expected status**: a code such as `200`, or a range such as `200-399` (the
   default).
6. (Optional) Change **Interval** (the default is every 5 minutes), **Down after** (the default is
   **2 failed runs in a row**) and **Timeout (seconds)** (1 to 30, the default 10).
7. (Optional) For **Email addresses (optional)**, enter up to ten addresses, and for
   **Webhook URL (optional)**, an `https://` URL.
8. Choose **Create check**.

The console's check uses `GET`, follows redirects, verifies the certificate and keeps the default
confirmations; set those with the CLI, the API or Terraform.

**CLI**
```sh
dcloud monitoring checks create --name Shop --url https://shop.example.com/health \
  --interval-seconds 60 --notify-emails oncall@example.com
```

A keyword check:

```sh
dcloud monitoring checks create --name Shop --url https://shop.example.com/health \
  --type keyword --keyword '"ok":true'
```

**API**
```http
POST /monitoring/api/checks
{ "name": "Shop", "url": "https://shop.example.com/health", "intervalSeconds": 60,
  "notifyEmails": ["oncall@example.com"] }
```

**Terraform**
```hcl
resource "dcloud_uptime_check" "shop" {
  name             = "Shop"
  url              = "https://shop.example.com/health"
  interval_seconds = 60
  notify_emails    = ["oncall@example.com"]
}
```

## Result

The check is `pending` and runs within a minute, then every interval. Its first successful run
makes it `up` without telling anyone (or `regional` when some locations failed, but fewer than
`confirmations`). It is `down` after its failed runs in a row reach **Down after**
(`failureThreshold`); a failed run is repeated after a minute rather than after the interval.

## When the check is refused

- `409` "A check named "Shop" already exists".
- `409` "shop.example.com is already checked … times a minute by …; at most 6 a minute across all
  checks. Choose a longer interval." when the checks of every organization already request the host
  that often.
- `409` with code `QuotaExceeded` past the **Uptime checks** quota.
- `400` when the URL is not allowed ("url: URL: port 25 is a mail port and is not checked",
  "url: URL: the URL points at a private or reserved address"), when the fields disagree ("A keyword
  check needs a keyword", "Only a keyword check has a keyword", "A keyword check reads the body, so
  it uses GET", "expectedStatusMin must not be above expectedStatusMax"), or when the interval is
  not one of 60, 120, 300, 600, 900, 1800 or 3600 seconds.

## Related

- [How uptime checks work](how-uptime-checks-work.md)
- [Read a check's results](read-check-results.md)
- `monitoring.checks.create` · `dcloud monitoring checks create` · `dcloud_uptime_check`
