# Status, uptime and history

Three questions a dashboard, a chat bot or a weekly report asks, each answered in one call: is everything up right
now, what was a monitor's uptime last month, and what happened hour by hour.

**Runnable code:** the code on this page, ready to clone and run, is in [`infranest-examples/examples/status-and-uptime`](https://github.com/InfraNest-Infrastructure-Organized/infranest-examples/tree/main/examples/status-and-uptime). CI runs it against the [sandbox](../sandbox.md).

## The token

Make a token with **Monitoring → Read**. Add **Servers → Read** if you want your servers in the status answer too;
without it, `servers` is `null`.

## Is everything up right now?

```sh
curl -fsS "https://api.infranest.io/api/organizations/42/status" \
  -H "Authorization: Bearer $INFRANEST_TOKEN" -H "Accept: application/json"
```

The answer lists every monitor and server with its current state, the open incidents and the maintenance running
now, and counts them in `summary`:

```json
{
  "summary": {
    "monitors": { "total": 13, "up": 11, "down": 1, "degraded": 0, "paused": 1, "unknown": 0 },
    "servers": { "total": 14, "running": 12, "agent_not_reporting": 1, "breaching": 0 },
    "open_incidents": 1,
    "active_maintenance": 0
  },
  "monitors": [{ "id": 3, "name": "API health", "status": "down", "last_checked_at": "2026-01-15T11:58:00Z", "uptime_24h": 99.4 }],
  "servers": [{ "id": 77, "name": "web-03", "status": "running", "agent_reporting": true, "breaching_alerts": 0 }],
  "incidents": [{ "id": 51, "title": "API health is down", "monitoring_check_id": 3, "started_at": "2026-01-15T11:20:00Z" }],
  "maintenance": []
}
```

- **One customer or one team:** add `?tag=7` to see only the monitors and servers with that tag, their incidents,
  and maintenance that carries the tag or covers them.
- **`agent_reporting`** is `true` while the server agent sends readings, `false` when it has gone quiet, and `null`
  when no agent is installed.
- **A traffic light** is `summary.monitors.down + summary.monitors.degraded == 0 && summary.open_incidents == 0`.

## Uptime and response times for a period

```sh
curl -fsS "https://api.infranest.io/api/organizations/42/monitoring-checks/3/aggregates?period=30d" \
  -H "Authorization: Bearer $INFRANEST_TOKEN" -H "Accept: application/json"
```

```json
{
  "period": "30d",
  "from": "2025-12-16T12:00:00Z",
  "to": "2026-01-15T12:30:00Z",
  "uptime_percent": 99.95,
  "up_percent": 99.81,
  "checks": { "total": 8640, "up": 8624, "degraded": 4, "down": 12 },
  "response_time_ms": { "p50": 182, "p95": 410 },
  "incidents": { "count": 2, "down_minutes": 21 }
}
```

- **`period`** is `24h`, `7d`, `30d` or `90d`. For a calendar month, send `from` and `to` instead:
  `?from=2026-01-01T00:00:00Z&to=2026-02-01T00:00:00Z` (up to 366 days).
- **`uptime_percent`** is the figure the app and your status page show: the share of the time no confirmed outage
  covered. **`up_percent`** is the share of individual checks that came back up, which a single probe's blip lowers.
- **Response times** over more than an hour are averaged from hourly figures, weighted by the number of checks, so
  they are close rather than exact.

For every monitor at once, by calendar month, the [monthly uptime report](/reference/monitoring) is one call:
`GET /organizations/42/uptime-report?month=2026-01`.

## Results hour by hour

```sh
curl -fsS "https://api.infranest.io/api/organizations/42/monitoring-checks/3/results?resolution=hour&from=2026-01-14T00:00:00Z&to=2026-01-15T00:00:00Z" \
  -H "Authorization: Bearer $INFRANEST_TOKEN" -H "Accept: application/json"
```

Each row sums one hour across all probes: `checks_total`, `checks_up`, `checks_degraded` (slow), `checks_down`
(failed), `up_percent` and the p50 and p95 response times. Newest first, 50 rows a page; ask for up to 500 with
`per_page` and follow `next_page_url`.

| `resolution` | Each row is | Longest range per request | Kept for |
|---|---|---|---|
| `raw` (default) | one check by one probe | 3 days | 3 days |
| `hour` | one hour, all probes | 31 days | your plan's history |
| `day` | one day, all probes | 366 days | your plan's history |

A longer range is refused with [`range_too_large`](../errors.md#range_too_large). The error says the longest range
the resolution takes in `max_range_seconds`, and which resolutions would take your range in `resolutions` — ask
for one of those, or split the range.

## Server metrics over a range

The same `from`, `to` and `resolution` work on a server's stored metrics:

```sh
curl -fsS "https://api.infranest.io/api/organizations/42/cloud-servers/77/metric-series?metrics=cpu_percent,memory_percent&from=2026-01-01T00:00:00Z&to=2026-01-15T00:00:00Z" \
  -H "Authorization: Bearer $INFRANEST_TOKEN" -H "Accept: application/json"
```

Raw samples are kept for 48 hours; past that, or for a range over 48 hours, the answer is hourly averages, and
`resolution` says which you got. Hourly averages go back up to 92 days per request. Each metric is a list of
`[unix seconds, value]` pairs, oldest first; `pagination` says how many points the range holds, 10,000 to a page.