Monitors

Monitors check the health of your services via HTTP, TCP, or ping.

List Monitors

GET/api/v1/monitorsFree

Returns a paginated list of all monitors in your organization.

Query parameters: limit (default 20, max 100), offset (default 0)

curl https://unstatus.app/api/v1/monitors?limit=10 \
  -H "Authorization: Bearer usk_your_key"

Response

{
  "data": [
    {
      "id": "clx1abc...",
      "name": "API Server",
      "type": "http",
      "active": true,
      "interval": 60,
      "timeout": 10,
      "url": "https://api.example.com/health",
      "method": "GET",
      "regions": ["eu"],
      "autoIncidents": false,
      "lastStatus": "up",
      "lastLatency": 142,
      "lastCheckedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": { "total": 1, "limit": 10, "offset": 0, "hasMore": false }
}

Get Monitor

GET/api/v1/monitors/:idFree

Returns a single monitor by ID.

curl https://unstatus.app/api/v1/monitors/clx1abc... \
  -H "Authorization: Bearer usk_your_key"

Create Monitor

POST/api/v1/monitorsAuthenticated

Creates a new monitor. Maximum 50 monitors per organization.

Request body:

Field	Type	Required	Description
`name`	string	Yes	Display name
`type`	string	Yes	`http`, `tcp`, or `ping`
`url`	string	For HTTP	URL to check
`host`	string	For TCP	Hostname
`port`	number	For TCP	Port number
`interval`	number	No	Check interval in seconds (min 10, default 60)
`timeout`	number	No	Timeout in seconds (default 10)
`method`	string	No	HTTP method (default `GET`)
`headers`	object	No	HTTP headers as key-value pairs
`body`	string	No	HTTP request body
`regions`	string[]	No	Regions to check from: `eu`, `us`, `asia` (default `["eu"]`)
`autoIncidents`	boolean	No	Auto-create incidents on failure (default false)
`rules`	array	No	Assertion rules for HTTP checks

curl -X POST https://unstatus.app/api/v1/monitors \
  -H "Authorization: Bearer usk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Server",
    "type": "http",
    "url": "https://api.example.com/health",
    "interval": 30,
    "regions": ["eu", "us"]
  }'

Response (201)

{
  "data": {
    "id": "clx1abc...",
    "name": "API Server",
    "type": "http",
    "active": true,
    "interval": 30,
    "url": "https://api.example.com/health",
    "regions": ["eu", "us"]
  }
}

Update Monitor

PATCH/api/v1/monitors/:idAuthenticated

Updates a monitor. Only include the fields you want to change.

curl -X PATCH https://unstatus.app/api/v1/monitors/clx1abc... \
  -H "Authorization: Bearer usk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "interval": 120, "active": false }'

Delete Monitor

DELETE/api/v1/monitors/:idAuthenticated

Permanently deletes a monitor and all its check history.

curl -X DELETE https://unstatus.app/api/v1/monitors/clx1abc... \
  -H "Authorization: Bearer usk_your_key"

List Checks

GET/api/v1/monitors/:id/checksFree

Returns paginated check history for a monitor (max 200 per page).

curl https://unstatus.app/api/v1/monitors/clx1abc.../checks?limit=5 \
  -H "Authorization: Bearer usk_your_key"

Response

{
  "data": [
    {
      "id": "chk_...",
      "monitorId": "clx1abc...",
      "status": "up",
      "latency": 142,
      "statusCode": 200,
      "region": "eu",
      "checkedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": { "total": 1440, "limit": 5, "offset": 0, "hasMore": true }
}

Trigger Check

POST/api/v1/monitors/:id/runAuthenticated

Triggers an on-demand check for a monitor.

curl -X POST https://unstatus.app/api/v1/monitors/clx1abc.../run \
  -H "Authorization: Bearer usk_your_key"