# Uptime

> Create uptime checks, read their status and results, and see when your app stopped answering.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/uptime/

For agents: Reference of the Uptime endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

An uptime check is a request the engine makes to a URL of yours on a schedule. A check is `down` after two
failures in a row and `up` again after one success. Going down and coming back each create an
[alert](https://docs.sypnia.com/api/webhooks).

A self-hosted engine checks from where it runs, so it sees your app from one place. Sypnia Cloud checks from
three regions and calls a check down when at least two of them fail.

## The uptime check object

**Fields:**

- `id` (string, optional): `chk_…`.
- `name` (string, optional)
- `url` (URL, optional)
- `method` (string, optional)
- `interval_seconds` (integer, optional)
- `timeout_ms` (integer, optional)
- `expected_status` (string, optional)
- `body_contains` (string or null, optional)
- `headers` (object, optional)
- `enabled` (boolean, optional)
- `status` (string, optional): `unknown` until the first check ran. One of: `up`, `down`, `paused`, `unknown`.
- `down_since` (timestamp or null, optional): The first failure of the current outage.
- `last_checked_at` (timestamp or null, optional)
- `last_status_code` (integer or null, optional): The HTTP status of the latest check. `null` when there was no answer.
- `last_response_ms` (integer or null, optional)
- `last_error` (string or null, optional): Why the latest check failed: `timeout`, `dns`, `connection_refused`, `tls`, `status_503`, `body_mismatch`.
- `uptime_24h` (number or null, optional): Percent of checks that passed in the last 24 hours.
- `uptime_30d` (number or null, optional)
- `created_at` (timestamp, optional)

## List uptime checks

`GET /v1/uptime/checks` \[Engine, Cloud]

Every check of the project with its current status. This is what the MCP tool `uptime` returns.

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `status` (string, optional): Only checks in this status. One of: `up`, `down`, `paused`, `unknown`.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/uptime/checks" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "chk_1q9w3e7r5t2y",
      "name": "Shop home",
      "url": "https://shop.example.com/",
      "method": "GET",
      "interval_seconds": 60,
      "timeout_ms": 10000,
      "expected_status": "200-399",
      "body_contains": null,
      "headers": {},
      "enabled": true,
      "status": "up",
      "down_since": null,
      "last_checked_at": "2026-03-12T10:34:00Z",
      "last_status_code": 200,
      "last_response_ms": 184,
      "last_error": null,
      "uptime_24h": 100,
      "uptime_30d": 99.98,
      "created_at": "2026-02-02T09:20:00Z"
    }
  ],
  "next_cursor": null
}
```

## Create an uptime check

`POST /v1/uptime/checks` \[Engine, Cloud]

Starts checking a URL. The first check runs within a minute. The engine sends the header
`User-Agent: Sypnia-Uptime/1.0`, follows up to 3 redirects and never sends cookies. Only `http` and `https`
URLs on public addresses are allowed: a URL that resolves to a private or loopback address is refused, so a
check cannot be used to reach inside your own network.

**Authentication:** API token (`admin`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Headers:**

- `Idempotency-Key` (string, up to 255 characters, optional): A value of your own, 1 to 255 characters, that makes the call safe to repeat. See [idempotency](https://docs.sypnia.com/api/errors-limits-pagination#idempotency).

**Body:**

- `name` (string, up to 80 characters, optional): A name for people. Required when creating.
- `url` (URL, up to 2,000 characters, optional): The URL to request. Required when creating.
- `method` (string, optional, default `GET`): The HTTP method. One of: `GET`, `HEAD`.
- `interval_seconds` (integer, optional, default `60`): How often to check. One of: `60`, `300`, `900`.
- `timeout_ms` (integer, 1,000 to 30,000, optional, default `10000`): An answer slower than this is a failure.
- `expected_status` (string, optional, default `200-399`): The statuses that count as up: one (`200`), a range (`200-299`) or a list (`200,204,301`).
- `body_contains` (string, up to 200 characters or null, optional): Text the answer's body must contain to count as up. Only with `GET`. The engine reads the first 256 KB.
- `headers` (object, optional): Up to 10 request headers. They are stored and returned as you send them, so do not put secrets here.
- `enabled` (boolean, optional, default `true`): `false` pauses the check.

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/uptime/checks" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop home", "url": "https://shop.example.com/"}'
```

**Response (201):**

```json
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 60,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": null,
  "headers": {},
  "enabled": true,
  "status": "unknown",
  "down_since": null,
  "last_checked_at": null,
  "last_status_code": null,
  "last_response_ms": null,
  "last_error": null,
  "uptime_24h": null,
  "uptime_30d": null,
  "created_at": "2026-02-02T09:20:00Z"
}
```

**Errors:**

- `400` `invalid_request`: The URL is not `http` or `https`, resolves to a private address, or a field is out of range. `param` names the field.
- `409` `limit_reached`: The project already has as many checks as its plan allows (Sypnia Cloud), or as `SYPNIA_QUOTA_UPTIME_CHECKS` allows (engine).

## Get an uptime check

`GET /v1/uptime/checks/{check_id}` \[Engine, Cloud]

One check with its current status.

**Authentication:** API token (`read`)

**Path parameters:**

- `check_id` (string, required): The check's id (`chk_…`).

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 60,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": null,
  "headers": {},
  "enabled": true,
  "status": "up",
  "down_since": null,
  "last_checked_at": "2026-03-12T10:34:00Z",
  "last_status_code": 200,
  "last_response_ms": 184,
  "last_error": null,
  "uptime_24h": 100,
  "uptime_30d": 99.98,
  "created_at": "2026-02-02T09:20:00Z"
}
```

**Errors:**

- `404` `not_found`: No check has this id in the project.

## Update an uptime check

`PATCH /v1/uptime/checks/{check_id}` \[Engine, Cloud]

Changes the fields you send and leaves the rest. Set `enabled` to `false` to pause a check; a paused check has status `paused` and creates no alerts.

**Authentication:** API token (`admin`)

**Path parameters:**

- `check_id` (string, required): The check's id (`chk_…`).

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Body:**

- `name` (string, up to 80 characters, optional): A name for people. Required when creating.
- `url` (URL, up to 2,000 characters, optional): The URL to request. Required when creating.
- `method` (string, optional, default `GET`): The HTTP method. One of: `GET`, `HEAD`.
- `interval_seconds` (integer, optional, default `60`): How often to check. One of: `60`, `300`, `900`.
- `timeout_ms` (integer, 1,000 to 30,000, optional, default `10000`): An answer slower than this is a failure.
- `expected_status` (string, optional, default `200-399`): The statuses that count as up: one (`200`), a range (`200-299`) or a list (`200,204,301`).
- `body_contains` (string, up to 200 characters or null, optional): Text the answer's body must contain to count as up. Only with `GET`. The engine reads the first 256 KB.
- `headers` (object, optional): Up to 10 request headers. They are stored and returned as you send them, so do not put secrets here.
- `enabled` (boolean, optional, default `true`): `false` pauses the check.

**Request:**

```bash
curl -X PATCH "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 300, "body_contains": "Add to cart"}'
```

**Response (200):**

```json
{
  "id": "chk_1q9w3e7r5t2y",
  "name": "Shop home",
  "url": "https://shop.example.com/",
  "method": "GET",
  "interval_seconds": 300,
  "timeout_ms": 10000,
  "expected_status": "200-399",
  "body_contains": "Add to cart",
  "headers": {},
  "enabled": true,
  "status": "up",
  "down_since": null,
  "last_checked_at": "2026-03-12T10:33:00Z",
  "last_status_code": 200,
  "last_response_ms": 184,
  "last_error": null,
  "uptime_24h": 100,
  "uptime_30d": 99.98,
  "created_at": "2026-02-02T09:20:00Z"
}
```

**Errors:**

- `400` `invalid_request`: A field is out of range. `param` names it.
- `404` `not_found`: No check has this id in the project.

## Delete an uptime check

`DELETE /v1/uptime/checks/{check_id}` \[Engine, Cloud]

Stops the check and deletes its results. Alerts it created stay.

**Authentication:** API token (`admin`)

**Path parameters:**

- `check_id` (string, required): The check's id (`chk_…`).

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errors:**

- `404` `not_found`: No check has this id in the project.

## Get an uptime check's results

`GET /v1/uptime/checks/{check_id}/results` \[Engine, Cloud]

The check's history: one bucket per hour with how many checks ran, how many failed and how long the answers
took, plus the incidents, each stretch of time the check was down. Single results are kept for 7 days and
hourly buckets for 400 days.

**Authentication:** API token (`read`)

**Path parameters:**

- `check_id` (string, required): The check's id (`chk_…`).

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `since` (string, optional, default `24h`): Start of the period.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

**Request:**

```bash
curl "https://api.sypnia.com/v1/uptime/checks/chk_1q9w3e7r5t2y/results?since=3h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "check_id": "chk_1q9w3e7r5t2y",
  "uptime": 99.44,
  "buckets": [
    {
      "start": "2026-03-12T08:00:00Z",
      "checks": 60,
      "failures": 0,
      "avg_ms": 181,
      "p95_ms": 240
    },
    {
      "start": "2026-03-12T09:00:00Z",
      "checks": 60,
      "failures": 1,
      "avg_ms": 190,
      "p95_ms": 262
    },
    {
      "start": "2026-03-12T10:00:00Z",
      "checks": 33,
      "failures": 0,
      "avg_ms": 184,
      "p95_ms": 251
    }
  ],
  "incidents": []
}
```

**Errors:**

- `404` `not_found`: No check has this id in the project.

The errors every endpoint can answer (`401`, `403`, `429`, `500`, `503`) are on [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination).
