---
title: "Events · API v1"
description: "Conditions that needed attention and whether they were acknowledged."
---
# Events

Conditions that needed attention and whether they were acknowledged.

## List events

`GET /events`

The attention feed, newest first: every condition that needed attention, with its deep link and whether it was acknowledged.

- Permission: `alert:read`
- Key scope: `read`, `full`

### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| `from` | `string` | Earliest date to include, YYYY-MM-DD (UTC). |
| `to` | `string` | Latest date to include, YYYY-MM-DD (UTC), inclusive. |
| `acknowledged` | `boolean` | true returns acknowledged events only, false open ones only. Omit for both. |
| `limit` | `integer` | Page size. Values above the maximum are clamped; zero, negative or non-numeric values are ignored and the default applies. Default 50. |
| `offset` | `integer` | Number of rows to skip; combine with limit to page. A negative or non-numeric value is treated as 0. Default 0. |

### Example request

```bash
curl "https://api.dmarcguard.io/api/v1/events?from=2026-01-01&to=2026-01-31" \
  -H "Authorization: Bearer dg_your_key"
```

### Response

| Field | Type | Notes |
| --- | --- | --- |
| `events` | `object[]` | The requested page, newest first. Never null; an empty page is []. |
| `events[].id` | `string` | Identifier, Crockford Base32. Opaque; never parse it as a number. |
| `events[].type` | `string` | What was detected. Read the type vocabulary from the enumerations endpoint instead of hardcoding it, and fall back to the raw value for a type you do not recognise. |
| `events[].type_label` | `string` | How DMARCguard writes the type for a reader. |
| `events[].severity` | `string` | How urgent the event is: info, warning or critical. Action items call the same three levels low, medium and high. |
| `events[].title` | `string` | One-line headline for the event. |
| `events[].message` | `string` | The detail behind the title, ready to show. |
| `events[].domain` | `string` | The domain the event is about; empty for an organization-wide event. |
| `events[].link` | `string` (optional) | Link to the screen where the event is resolved. |
| `events[].acknowledged` | `boolean` | True once the underlying item was marked handled. Acknowledging happens in the app, not through this endpoint. |
| `events[].created_at` | `string` (nullable) | RFC 3339 UTC instant with whole seconds, e.g. 2026-09-15T16:03:43Z; null when absent. |
| `total` | `integer` | Events matching the filter, before paging. |
| `limit` | `integer` | The page size actually applied. |
| `offset` | `integer` | The offset actually applied. |

### Errors

| Status | When |
| --- | --- |
| `400` | from or to is not YYYY-MM-DD. |
| `401` | Missing, malformed, revoked, expired or not-entitled API key. |
| `403` | The key's scope or its owner's role does not allow this operation. |
| `429` | Hourly quota or an abuse limit exceeded; the body's code says which. Honour Retry-After. |
| `500` | Unexpected server error; retry with backoff. |
| `503` | A transient failure resolving the organization or reading storage; retry after a short pause. |

Plus the errors every request can return: https://dmarcguard.io/docs/api/v1/#errors