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

# Events API: paginate and filter check result history

> Paginate through check results across all monitors in your organization, filter by monitor type or status, and navigate pages with cursor-based pagination.

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

<ParamField query="limit" type="number">
  Number of events to return per page. Maximum `200`, default `50`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor from a previous response. Pass this to retrieve the next page of results.
</ParamField>

<ParamField query="type" type="string">
  Filter events to monitors of this type. One of `HTTP`, `TCP`, `TLS`, `DNS`, `SCHEDULED`.
</ParamField>

<ParamField query="status" type="string">
  Filter events to those with this exact status value, e.g. `down`, `expiring_soon`, `havent_heard`.
</ParamField>

### Response

```json theme={null}
{
  "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..."
}
```

<ResponseField name="data" type="CheckResult[]">
  Array of check result objects, each augmented with a `monitor` summary.

  <Expandable title="CheckResult fields">
    <ResponseField name="id" type="string">Unique check result ID. Used as the pagination cursor value.</ResponseField>
    <ResponseField name="monitorId" type="string">ID of the monitor that produced this result.</ResponseField>
    <ResponseField name="status" type="string">Status recorded for this check. See [Monitor statuses](/api-reference/monitors#monitor-statuses) for values by type.</ResponseField>
    <ResponseField name="latencyMs" type="number | null">Round-trip latency in milliseconds. `null` for monitors where latency is not measured (e.g. DNS, SCHEDULED).</ResponseField>
    <ResponseField name="detail" type="object | null">Structured detail payload from the worker. Contents vary by monitor type and outcome.</ResponseField>
    <ResponseField name="alertTriggered" type="boolean">Whether an alert was attempted for this check result.</ResponseField>
    <ResponseField name="alertOutcome" type="object | null">Outcome of the alert attempt. `null` if no alert was triggered.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp of when the check ran.</ResponseField>

    <ResponseField name="monitor" type="object">
      Summary of the monitor that produced this event.

      <Expandable title="monitor fields">
        <ResponseField name="id" type="string">Monitor ID.</ResponseField>
        <ResponseField name="name" type="string">Monitor display name.</ResponseField>
        <ResponseField name="type" type="string">Monitor type.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cursor" 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.
</ResponseField>

***

## Pagination

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

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

```bash theme={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"
```

<Note>
  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.
</Note>

***

## Examples

### Filter by status

```bash theme={null}
# 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

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

### Combine filters

```bash theme={null}
# 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"
```