> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dnsradar.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# List events for monitor
> Get a paginated list of DNS changes (as events) detected for a specific monitor.
An events is recorded each time a DNS change is detected for the monitor or when a monitor stays on an invalid state. In that last case, the `incidence_count` increases and triggers an event.
You can filter the events by either `occurred_before` or `occurred_after`, as UTC Timestamps.
You can use the pagination parameters to navigate through the list of events.
## OpenAPI
````yaml https://api.dnsradar.dev/openapi.json get /monitors/{monitor_id}/events
openapi: 3.0.3
info:
title: DNSRadar API
description: DNSRadar API - Monitor your DNS records and get notified when they change.
version: 1.0.0
contact:
name: DNSRadar Support
email: support@dnsradar.dev
url: https://dnsradar.dev
servers:
- url: https://api.dnsradar.dev
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Agents
description: Team member management and invitations
- name: Organization
description: Organization settings, billing, and subscription management
- name: Monitors
description: DNS monitoring configuration and management
- name: Events
description: DNS change events and history
- name: Groups
description: Monitor grouping and organization
- name: Webhooks
description: Webhook configuration for event notifications
paths:
/monitors/{monitor_id}/events:
get:
tags:
- Events
summary: List events for monitor
description: >-
Get a paginated list of DNS changes (as events) detected for a specific
monitor.
operationId: listEvents
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
description: Monitor UUID
- $ref: '#/components/parameters/PaginationAfter'
- $ref: '#/components/parameters/PaginationBefore'
- $ref: '#/components/parameters/PaginationLimit'
- $ref: '#/components/parameters/PaginationOrderBy'
- $ref: '#/components/parameters/PaginationOrderWay'
- name: occurred_before
in: query
description: Filter events that occurred before this UTC timestamp
schema:
type: integer
format: int64
- name: occurred_after
in: query
description: Filter events that occurred after this UTC timestamp
schema:
type: integer
format: int64
- name: old_state
in: query
description: Filter events by old state
schema:
type: string
enum:
- UNSET
- VALID
- INVALID
- TIMEOUT
- MISMATCH
- NOT_FOUND
- NO_DATA
- BAD_SETUP
- name: new_state
in: query
description: Filter events by new state
schema:
type: string
enum:
- VALID
- INVALID
- TIMEOUT
- MISMATCH
- NOT_FOUND
- NO_DATA
- BAD_SETUP
responses:
'200':
description: Paginated list of events
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Event'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: Monitor not found
security:
- ApiKeyAuth: []
components:
parameters:
PaginationAfter:
name: after
in: query
description: >-
Cursor for fetching the next page of results. Use the value from the
previous response's 'after' field.
schema:
type: string
PaginationBefore:
name: before
in: query
description: >-
Cursor for fetching the previous page of results. Use the value from the
previous response's 'before' field.
schema:
type: string
PaginationLimit:
name: limit
in: query
description: 'Number of items per page (1-100, default: 20)'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
PaginationOrderBy:
name: order_by
in: query
description: Field to order results by
schema:
type: string
PaginationOrderWay:
name: order_way
in: query
description: Sort direction
schema:
type: string
enum:
- asc
- desc
default: asc
schemas:
PaginatedResponse:
type: object
description: >-
Paginated response wrapper for list endpoints. Uses cursor-based
pagination with after/before parameters.
properties:
limit:
type: integer
description: Number of items per page (max 100)
example: 20
after:
type: string
nullable: true
description: Cursor to fetch the next page of results
before:
type: string
nullable: true
description: Cursor to fetch the previous page of results
has_more:
type: boolean
description: Indicates if there are more items to fetch
data:
type: array
description: Array of items for the current page
items:
type: object
Event:
type: object
description: DNS change event detected by monitoring
properties:
id:
type: string
description: Event identifier with 'evt_' prefix
example: evt_abc123...
monitor_id:
type: string
description: UUID of the associated monitor
example: mon_abc123...
monitor:
type: object
description: Monitor information associated with this event
properties:
domain:
type: string
description: Domain name to monitor
example: example.com
subdomain:
type: string
description: Subdomain to monitor (empty string for apex)
example: www
record_type:
type: string
enum:
- A
- AAAA
- CNAME
- MX
- TXT
- NS
- PTR
- SPF
- CAA
description: DNS record type to monitor
expected_value:
type: array
items:
type: string
description: Expected DNS record values (up to 10)
example:
- 192.168.1.1
occurred:
type: string
format: date-time
description: Datetime when the event occurred in ISO 8601 format
previous_value:
type: array
items:
type: string
nullable: true
description: Previous DNS values
example:
- 192.168.1.1
current_value:
type: array
items:
type: string
nullable: true
description: New DNS values
example:
- 10.0.0.1
old_state:
type: string
enum:
- UNSET
- VALID
- INVALID
- TIMEOUT
- MISMATCH
- NOT_FOUND
- NO_DATA
- BAD_SETUP
description: Previous monitoring state
example: MISMATCH
new_state:
type: string
enum:
- VALID
- INVALID
- TIMEOUT
- MISMATCH
- NOT_FOUND
- NO_DATA
- BAD_SETUP
description: New monitoring state
example: VALID
incidence_count:
type: integer
description: Total number of incidents for the monitor.
example: 0
Error:
type: object
description: Error response
properties:
code:
type: integer
description: HTTP status code
error:
oneOf:
- type: string
description: Error message
- type: object
description: Validation errors by field
additionalProperties:
type: string
errors:
type: object
description: Field-specific validation errors
additionalProperties:
type: string
responses:
UnauthorizedError:
description: Authentication is missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 401
error: Unauthorized
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-Api-Key
description: >-
API key used to authenticate yourself on DNSRadar. Obtain your API key
from your DNSRadar dashboard.
````