# REST API: events

Adresse: https://docs.athaus.ai/en/api/v1/ereignisse

> What happened in the office, available for 30 days. The same events that go to webhooks, filtered by type and time.

Type: Guide
Last updated: 2026-11-14

`GET /v1/events` returns what happened in the office: new inquiries and messages, booked, canceled and upcoming viewings, files that were read. These are the same events a [webhook](/en/api/v1/webhooks) receives, with the same id. Use the list when you have no address, missed a webhook, or want to catch up after an outage.

```bash
curl "https://api.athaus.ai/v1/events?type=inquiry.received&limit=2" \
  -H "Authorization: Bearer ath_live_..."
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44",
      "type": "inquiry.received",
      "createdAt": "2026-11-12T08:14:03.512Z",
      "apiVersion": "v1",
      "livemode": true,
      "data": {
        "object": {
          "object": "inquiry",
          "id": "0190f3c1-2217-7a02-8c4b-5e1d7a9b3f10",
          "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
          "status": "new",
          "source": "athaus",
          "answered": false,
          "replyable": true,
          "name": "Mia K.",
          "email": null,
          "phone": null,
          "contactId": null,
          "contactConsent": "not_requested",
          "seeker": null,
          "createdAt": "2026-11-12T08:14:03Z",
          "updatedAt": "2026-11-12T08:14:03Z"
        }
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJzIjoiLWNyZWF0ZWRBdCIsLi4ufQ"
}
```

## What an event is [#what-an-event-is]

`{ object: "event", id, type, createdAt, apiVersion, livemode, data: { object } }`.

* `type` is one of the names in the [webhook table](/en/api/v1/webhooks#events). New types arrive without a new version: ignore what you do not know.
* `data.object` is the resource the event is about, in the shape `/v1` reads it. It is in the state of now, not in the state of the event: if you need the state of back then, you have to keep it when it is delivered. If the resource no longer exists, you get `{ "object": "viewing", "id": "...", "deleted": true }` instead.
* What a `GET` does not return is not here either. Name, email and phone of a seeker appear only while they have released them to the office.
* `apiVersion` is the version the `data` is shaped in.
* `livemode` is `false` for an event of the [test office](/en/api/v1/testmodus).

## How long, and who sees what [#how-long-and-who-sees-what]

An event is available for 30 days; after that `GET /v1/events/{id}` answers `404` and the list no longer shows it.

A key sees only the events of the resources it may read: without `read` on `viewings` it misses the three viewing types. It sees `proposal.pending` only for proposals it created itself. Asking for a `type` outside that is `403` (`insufficient_permissions`). A single event outside it is `404`. The list needs the scope `read`, but no level on a resource of its own.

## Filter and page [#filter-and-page]

| Parameter         | Effect                                                 |
| ----------------- | ------------------------------------------------------ |
| `type`            | only events of this type                               |
| `createdSince`    | only events from this instant on (ISO 8601, inclusive) |
| `createdBefore`   | only events before this instant                        |
| `limit`, `cursor` | as everywhere, see [Pagination](/en/api/v1/blaettern)  |

The list is sorted by `createdAt` descending, newest first, and the order is fixed. There is no `sort` and no `updatedSince`: an event never changes.

## Catch up after an outage [#catch-up-after-an-outage]

Keep the `id` of the newest event you processed and the time of its `createdAt`. Read with `createdSince` from that time, page to the end and skip what you already have. Events with the same time arrive exactly once, also across page boundaries.

```bash
curl "https://api.athaus.ai/v1/events/0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44" \
  -H "Authorization: Bearer ath_live_..."
```

Both operations are in the [reference](/en/api/v1/referenz/list-events).
