---
title: "List TCP Monitors"
description: "Lists TCP monitors in an organization."
---

`GET /api/tcp-monitors`

## Authentication

Requires a valid session.

- Header: `Authorization: Bearer <token>`

## Parameters

- `organizationId` (Query, optional): Organization ID. Defaults to the current user's organization.
- `customerId` (Query, optional): Filter by customer ID.
- `search` (Query, optional): Search by monitor name, hostname, or customer.
- `page` (Query, optional): Page number (default: 1).
- `perPage` (Query, optional): Items per page (default: 50, max: 200).

## cURL

```bash
curl "https://YOUR_DOMAIN/api/tcp-monitors?page=1&perPage=50" \
  -H "Authorization: Bearer $TOKEN"
```

## Response

```json
{
  "items": [
    {
      "id": 300,
      "publicId": "44444444-4444-4444-8444-444444444444",
      "organizationId": 1,
      "customerId": 10,
      "name": "Redis Primary",
      "hostname": "redis.deinkunde.com",
      "port": 6379,
      "status": "active",
      "managementType": "managed",
      "checkInterval": 60,
      "timeoutSeconds": 30,
      "customerName": "Example Customer",
      "notificationEmail": null,
      "notificationPhoneNumber": null,
      "lastCheckedAt": "2026-02-26T12:00:00.000Z",
      "createdAt": "2026-02-26T12:00:00.000Z",
      "updatedAt": "2026-02-26T12:00:00.000Z",
      "config": {
        "expectBanner": "+PONG"
      },
      "tags": []
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 50
}
```

## Inline metrics

Every item carries the same rolled-up metrics the other monitor list endpoints return. They are
computed per monitor over the calendar day, month and year in UTC.

| Field | Type | Meaning |
|------|-----|---------|
| `uptimeDay` / `uptimeMonth` / `uptimeYear` | string | Uptime percentage with two decimals, e.g. `"99.94"` |
| `avgResponseDay` / `avgResponseMonth` / `avgResponseYear` | number \| null | Average response time in milliseconds; `null` when nothing was measured in that window |
| `responseGraph` | object | `{ values, avg }` for the last 24 hours, one entry per hour; an hour with no successful check is `null` |
| `upSinceAt` | string \| null | ISO timestamp the monitor has been up since, `null` while it is down |
| `isDown` | boolean | Whether the monitor is currently in an unresolved incident |

The day figures are read from the raw check data, the month and year from continuous aggregates,
so a value may lag the newest check by a few minutes in the month and year windows.

## Errors

- `400` Invalid `organizationId` or `customerId`
- `401` Unauthorized
- `403` Forbidden