# View Monitor Event History

Every DNS change detected by a monitor creates an event. The events API provides access to this history for analysis, debugging, and compliance.

## Listing Events for a Monitor

Get all events for a specific monitor:

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events
```

### Response

```json
{
  "limit": 20,
  "after": "evt_xyz789",
  "before": null,
  "has_more": true,
  "data": [
    {
      "uuid": "evt_def456",
      "monitor_uuid": "mon_abc123",
      "domain": "piedpiper.com",
      "subdomain": "www",
      "record_type": "A",
      "expected_value": ["1.2.3.4"],
      "occurred": "2026-01-08T14:22:10Z",
      "previous_value": ["1.2.3.4"],
      "current_value": ["5.6.7.8"],
      "old_state": "VALID",
      "new_state": "MISMATCH",
      "incidence_count": 3
    }
  ]
}
```

## Pagination

Events use cursor-based pagination:

### Next Page

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?after=evt_xyz789&limit=50
```

### Previous Page

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?before=evt_abc123&limit=50
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | integer | Results per page (1-100, default: 20) |
| `after` | string | Cursor for next page |
| `before` | string | Cursor for previous page |
| `order_by` | string | Sort field (e.g., `occurred`) |
| `order_way` | string | Sort direction (`asc` or `desc`) |
| `occurred_after` | integer | Unix timestamp - events after this time |
| `occurred_before` | integer | Unix timestamp - events before this time |
| `old_state` | string | Filter by state (`VALID`, `MISMATCH`, `NOT_FOUND`, `TIMEOUT`, `INVALID`) |
| `new_state` | string | Filter by state (`VALID`, `MISMATCH`, `NOT_FOUND`, `TIMEOUT`, `INVALID`) |

## Filtering Events

### Filter by Time Range

Get events within a specific time period using Unix timestamps (seconds since epoch).

**Events after a specific time:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?occurred_after=1767793661
```

**Events before a specific time:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?occurred_before=1767880061
```

**Events within a time range:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?occurred_after=1767793661&occurred_before=1767880061
```

> ℹ️ **INFO:** **Unix Timestamps**: Convert dates to Unix timestamps using `date +%s` in Bash, `Date.now() / 1000` in JavaScript, or `int(time.time())` in Python.

### Filter by State

Get only events with a specific state.

**DNS mismatches only:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=MISMATCH
```

**Missing DNS records:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=NOT_FOUND
```

**Valid states (back to normal):**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=VALID
```

**Timeout errors:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=TIMEOUT
```

**Invalid DNS responses:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=INVALID
```

### Sorting Options

Sort by occurred timestamp (descending):

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?order_by=occurred&order_way=desc
```

Sort by occurred timestamp (ascending):

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?order_by=occurred&order_way=asc
```

### Combining Filters

You can combine multiple filters to create powerful queries.

**Recent MISMATCH events (last 24 hours):**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=MISMATCH&occurred_after=1767793661&order_by=occurred&order_way=desc&limit=50
```

**All errors in a specific time range:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=TIMEOUT&occurred_after=1767793661&occurred_before=1767880061&order_by=occurred&order_way=asc
```

**Latest 100 events, sorted newest first:**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?order_by=occurred&order_way=desc&limit=100
```

**Recovery events (state changed to VALID):**

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events?new_state=VALID&occurred_after=1767793661&limit=20
```

## Get Single Event

Retrieve details for a specific event:

```
GET https://api.dnsradar.dev/monitors/mon_abc123/events/evt_def456
```

## Event Fields

| Field | Description |
|-------|-------------|
| `uuid` | Unique event identifier (evt_) |
| `monitor_uuid` | Associated monitor ID |
| `domain` | Domain name |
| `subdomain` | Subdomain (if applicable) |
| `record_type` | DNS record type |
| `expected_value` | Expected DNS values |
| `occurred` | ISO 8601 timestamp |
| `previous_value` | DNS value before change |
| `current_value` | DNS value after change |
| `old_state` | Previous monitor state |
| `new_state` | Current monitor state |
| `incidence_count` | Total incidents for this monitor |

## Monitor States

Events track state transitions:

| State | Meaning |
|-------|---------|
| `VALID` | DNS matches expected value |
| `MISMATCH` | DNS doesn't match |
| `NOT_FOUND` | DNS record missing |
| `TIMEOUT` | DNS query timeout |
| `INVALID` | Invalid DNS response |


## Next Steps

- [View Webhook Request History](/docs/webhook-requests)
- [Configure Webhooks](/docs/configure-webhooks)
- [Enable/Disable Monitors](/docs/enable-disable-monitors)