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

# List Monitors

> List the monitors in a project with filtering, sorting and pagination

## Overview

Return the monitors in a project, newest first by default. Each monitor includes its current health and a 30-day statistics summary.

```
GET https://api.uptimeio.com/api/monitors
```

## Authentication

| Header | Required | Description |
| - | - | - |
| `X-API-Key` | Yes (or a Bearer token) | Any API key, including read-only keys. See [Authentication](/api-reference/authentication). |
| `X-Project-ID` | No | Project to list. Defaults to your organization's default project. |

## Query parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | integer | `50` | Page size, 1-100. |
| `offset` | integer | `0` | Number of monitors to skip. |
| `status` | enum | none | `active` returns active monitors. `paused` or `disabled` returns every monitor that is not active. |
| `type` | enum | none | One of `HTTP`, `KEYWORD`, `ICMP`, `TCP`, `DNS`, `HEARTBEAT`. |
| `types` | string | none | Comma-separated list of types, for example `HTTP,KEYWORD`. Takes precedence over `type`. Unknown values are ignored. |
| `search` | string | none | Case-insensitive match on the monitor name or target. |
| `group_id` | UUID | none | Only monitors in this group. |
| `tags` | string | none | Comma-separated tags. Monitors with **any** of them match. |
| `sort_by` | enum | `created_at` | `created_at`, `updated_at` or `name`. `last_check_at` is accepted but sorts by creation time. |
| `sort_order` | enum | `desc` | `asc` or `desc`. |

An invalid value returns `VALIDATION_ERROR` (400).

## Response

### 200 OK

```json theme={null}
{
  "success": true,
  "data": {
    "monitors": [
      {
        "id": "b7a2c1de-3f54-4c21-9d0a-6e1f2a3b4c5d",
        "organization_id": "0c9e8d7f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
        "created_by": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
        "name": "Production API",
        "target": "https://api.example.com/health",
        "type": "HTTP",
        "interval_seconds": 60,
        "status": "active",
        "configState": "active",
        "created_at": 1767000000,
        "updated_at": 1767003600,
        "last_check_at": 1767090000,
        "next_check_at": 1767090060,
        "runtimeStatus": "up",
        "stats": {
          "uptime": 99.98,
          "averageResponseTime": 184.2,
          "totalChecks": 43200,
          "failedChecks": 0,
          "lastChecked": "2026-09-30T08:20:00.000Z",
          "lastFailureAt": null,
          "lastSuccessAt": 1767090000000,
          "currentIncident": null
        }
      }
    ],
    "pagination": {
      "total_count": 1,
      "limit": 50,
      "offset": 0,
      "has_more": false
    }
  }
}
```

### Monitor fields

Each entry has the core fields described in [Get Monitor](/api-reference/monitors/get) (type-specific fields are included too), plus:

| Field | Type | Description |
| - | - | - |
| `last_check_at` | integer | Time of the most recent check. Omitted until the first check. |
| `next_check_at` | integer | Time the next check is due. Omitted when not scheduled. |
| `group_id`, `group_name` | string | Present when the monitor belongs to a group. |
| `runtimeStatus` | enum | `up`, `down`, `degraded` or `unknown`. |
| `stats` | object | 30-day summary (below). Omitted if it could not be computed. |

### `stats` fields

| Field | Type | Description |
| - | - | - |
| `uptime` | number | Uptime percentage over the last 30 days. |
| `averageResponseTime` | number | Average response time in milliseconds. |
| `totalChecks` | integer | Checks recorded in the period. |
| `failedChecks` | integer | Failed checks recorded in the period. |
| `lastChecked` | string \| null | ISO 8601 time of the latest check. |
| `lastFailureAt`, `lastSuccessAt` | integer \| null | Unix time in milliseconds. |
| `currentIncident` | object \| null | Open incident: `id`, `startedAt`, `downtimeMinutes`, `status` (`open` or `acknowledged`), `severity`. |

### `pagination` fields

| Field | Type | Description |
| - | - | - |
| `total_count` | integer | Monitors matching the filters. |
| `limit` | integer | Page size used. |
| `offset` | integer | Offset used. |
| `has_more` | boolean | `true` when more monitors follow this page. |

To fetch the next page, add `limit` to `offset` and request again until `has_more` is `false`.

## Errors

| Code | Status | Meaning |
| - | - | - |
| `VALIDATION_ERROR` | 400 | A query parameter is invalid. |
| `AUTHENTICATION_REQUIRED` / `MISSING_AUTH` / `INVALID_API_KEY` | 401 | Missing or invalid credentials. |
| `INSUFFICIENT_PERMISSIONS` | 403 | Your role cannot view monitors. |
| `MONITORS_FETCH_FAILED` | 400 | The list could not be loaded. |

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.uptimeio.com/api/monitors?types=HTTP,KEYWORD&status=active&limit=20" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ types: 'HTTP,KEYWORD', status: 'active', limit: '20' });
  const res = await fetch(`https://api.uptimeio.com/api/monitors?${params}`, {
    headers: { 'X-API-Key': process.env.UPTIMEIO_API_KEY },
  });
  const { data } = await res.json();
  console.log(data.pagination.total_count, data.monitors.length);
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.get(
      "https://api.uptimeio.com/api/monitors",
      headers={"X-API-Key": os.environ["UPTIMEIO_API_KEY"]},
      params={"types": "HTTP,KEYWORD", "status": "active", "limit": 20},
  )
  data = res.json()["data"]
  print(data["pagination"]["total_count"], len(data["monitors"]))
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.