Events API: paginate and filter check result history

Events are individual check results — one record per check run, across all monitors in your organization. Each event captures what happened: the status, latency, whether an alert fired, and which monitor produced it. The events endpoint is useful for building audit logs, feeding external observability tools, or triggering downstream workflows based on specific status transitions.

List events

GET /api/v1/events

Returns check results across all monitors in your organization, ordered by most recent first. Supports cursor-based pagination and filtering by monitor type or status value.

Query parameters

number

Number of events to return per page. Maximum 200, default 50.

string

Opaque cursor from a previous response. Pass this to retrieve the next page of results.

string

Filter events to monitors of this type. One of HTTP, TCP, TLS, DNS, SCHEDULED.

string

Filter events to those with this exact status value, e.g. down, expiring_soon, havent_heard.

Response

{
  "data": [
    {
      "id": "res_01j...",
      "monitorId": "mon_01j...",
      "status": "down",
      "latencyMs": null,
      "detail": { "error": "connection refused" },
      "alertTriggered": true,
      "alertOutcome": { "channel": "alc_01j...", "ok": true },
      "createdAt": "2025-04-15T10:05:00.000Z",
      "monitor": {
        "id": "mon_01j...",
        "name": "API health",
        "type": "HTTP"
      }
    }
  ],
  "cursor": "res_01j..."
}

CheckResult[]

Array of check result objects, each augmented with a monitor summary.

Show CheckResult fields

string

Unique check result ID. Used as the pagination cursor value.

string

ID of the monitor that produced this result.

string

Status recorded for this check. See Monitor statuses for values by type.

number | null

Round-trip latency in milliseconds. null for monitors where latency is not measured (e.g. DNS, SCHEDULED).

object | null

Structured detail payload from the worker. Contents vary by monitor type and outcome.

boolean

Whether an alert was attempted for this check result.

object | null

Outcome of the alert attempt. null if no alert was triggered.

string

ISO 8601 timestamp of when the check ran.

object

Summary of the monitor that produced this event.

Show monitor fields

string

Monitor ID.

string

Monitor display name.

string

Monitor type.

string | null

Pass this value as ?cursor= in your next request to retrieve the following page. Returns null when there are no more results.

Pagination

Events use cursor-based pagination. To page through all results:

Make an initial request without a cursor.
If the response includes a non-null cursor, pass it as ?cursor= in your next request.
Repeat until cursor is null.

# Page 1
curl "https://overwatchapp.dev/api/v1/events?limit=50" \
  -H "Authorization: Bearer $API_KEY"

# Page 2 — use the cursor from the previous response
curl "https://overwatchapp.dev/api/v1/events?limit=50&cursor=res_01j..." \
  -H "Authorization: Bearer $API_KEY"

Cursors are not stable across schema changes. Do not persist cursors across sessions for long-lived polling — restart from the beginning and rely on createdAt timestamps to deduplicate if needed.

Examples

Filter by status

# All check results where the monitor went down
curl "https://overwatchapp.dev/api/v1/events?status=down" \
  -H "Authorization: Bearer $API_KEY"

Filter by monitor type

# All TLS check results
curl "https://overwatchapp.dev/api/v1/events?type=TLS" \
  -H "Authorization: Bearer $API_KEY"

Combine filters

# TLS checks that returned expiring_soon
curl "https://overwatchapp.dev/api/v1/events?type=TLS&status=expiring_soon&limit=200" \
  -H "Authorization: Bearer $API_KEY"

Overview

Endpoints

Events API: paginate and filter check result history

List events

Query parameters

Response

Examples

Filter by status

Filter by monitor type

Combine filters

​List events

​Query parameters

​Response

​Pagination

​Examples

​Filter by status

​Filter by monitor type

​Combine filters

List events

Query parameters

Response

Pagination

Examples

Filter by status

Filter by monitor type

Combine filters