# Events

Source: https://docs.mirafive.io/rest-api/events

> Read the raw events a MIRA FIVE project received in the last hour, day or week, newest first, with filters and a cursor.

The events endpoint lists raw events as **Data → Events** shows them: newest first, with page, device, consent, revenue and the person. Use it to check that tracking arrives, or to see what one visit did. It reads short windows only. For totals over longer periods, read the [overview](https://docs.mirafive.io/rest-api/overview) or [goals](https://docs.mirafive.io/rest-api/goals).

## List events

```text
GET /api/v1/projects/{project_id}/events
```

Events of the period, newest first, 50 per page.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `period` | string | `24h` | `1h`, `24h` or `7d`, ending now. |
| `filters[i][field]`, `filters[i][op]`, `filters[i][value]` | string | none | Event filters, all of which must hold. See [Filters](https://docs.mirafive.io/rest-api#filters). |
| `cursor` | string | none | `meta.nextCursor` of the previous page. See [Pagination](https://docs.mirafive.io/rest-api#pagination). |

`from`, `to` and `compare` are refused. `period=custom` and the longer presets get `422`.

```bash
curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/events \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'period=1h'
```

```json title="200 OK"
{
  "data": [
    {
      "id": "0199a3f2-4c1d-7e8a-b2c3-d4e5f6a7b8c9",
      "type": "events",
      "attributes": {
        "name": "order_completed",
        "kind": "custom",
        "occurredAt": "2026-09-27T10:14:02.512+02:00",
        "path": "/checkout/thank-you",
        "host": "shop.nordlicht.example",
        "title": "Thank you for your order",
        "referrer": "",
        "country": "DE",
        "device": "desktop",
        "browser": "Firefox",
        "sourceType": "first_party_web",
        "consented": true,
        "visit": "0199a3e8-0b1c-7d2e-9f3a-4b5c6d7e8f90",
        "revenue": { "amount": 89.9, "currency": "EUR" },
        "person": {
          "ref": "0196f0a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a",
          "name": "Lena Hoffmann",
          "known": true
        }
      }
    },
    {
      "id": "0199a3f1-9e8d-7c6b-a5f4-e3d2c1b0a9f8",
      "type": "events",
      "attributes": {
        "name": "$pageview",
        "kind": "pageview",
        "occurredAt": "2026-09-27T10:13:40.087+02:00",
        "path": "/products/wool-scarf",
        "host": "shop.nordlicht.example",
        "title": "Wool scarf, graphite",
        "referrer": "instagram.com",
        "country": "AT",
        "device": "mobile",
        "browser": "Safari",
        "sourceType": "first_party_web",
        "consented": false,
        "visit": null,
        "revenue": null,
        "person": null
      }
    }
  ],
  "links": {
    "self": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/events?period=1h",
    "next": "https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/events?period=1h&cursor=eyJhdCI6IjIwMjYtMDktMjcgMDg6MTM6NDAuMDg3In0"
  },
  "meta": {
    "period": {
      "preset": "1h",
      "from": "2026-09-27T09:15:00+02:00",
      "to": "2026-09-27T10:15:00+02:00",
      "timezone": "Europe/Berlin",
      "interval": "minute",
      "comparison": null,
      "clampedToRetention": false
    },
    "perPage": 50,
    "nextCursor": "eyJhdCI6IjIwMjYtMDktMjcgMDg6MTM6NDAuMDg3In0"
  }
}
```

The second event came without consent, so it has no visit and no person.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The event's id. |
| `attributes.name` | string | The event name, e.g. `$pageview` or `order_completed`. |
| `attributes.kind` | string | `pageview` (`$pageview`), `click` (`$autocapture`), `identify` (`$identify`), `search` (`$search`) or `custom`. |
| `attributes.occurredAt` | string | When it happened, in the project's timezone with milliseconds. |
| `attributes.path`, `attributes.host`, `attributes.title` | string | The page it happened on. Empty for server events without a page. |
| `attributes.referrer` | string | The referring host, empty when there was none. |
| `attributes.country` | string | Two-letter country code, empty when unknown. |
| `attributes.device` | string | `desktop`, `mobile` or `tablet`, empty when unknown. |
| `attributes.browser` | string | e.g. `Chrome`, `Safari`, `Firefox`. |
| `attributes.sourceType` | string | `first_party_web` (a website source) or `first_party_server` (a server source). |
| `attributes.consented` | boolean | Collected with consent ([full mode](https://docs.mirafive.io/guides/consent#full-mode)). |
| `attributes.visit` | string or null | The visit (session) id. `null` for consentless events and server events without one. |
| `attributes.revenue` | object or null | `amount` and `currency` when the event carried revenue. |
| `attributes.person` | object or null | `ref` (for [Get a person](https://docs.mirafive.io/rest-api/people#get-a-person)), `name` and `known`. `null` for consentless events and server events without a person. |
| `meta.period` | object | The window read. See [Periods](https://docs.mirafive.io/rest-api#periods). |
| `meta.perPage`, `meta.nextCursor` | | See [Pagination](https://docs.mirafive.io/rest-api#pagination). |

To find events of one kind, filter by name:

```bash
curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/events \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'period=7d' \
  --data-urlencode 'filters[0][field]=event_name' \
  --data-urlencode 'filters[0][op]=is' \
  --data-urlencode 'filters[0][value]=order_completed'
```