# REST API: pagination

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

> Every list of /v1 returns one page and a way to the next. Listings use a page token, the other resources a cursor. No total count.

Type: Reference
Last updated: 2026-11-16

Every list of `/v1` comes in pages. You fetch the first page and send the token from the response with the next request, until there is no further page. Listings follow OpenImmo and page with a **page token**. The other resources page with a **cursor**.

## Listings: nextPageToken [#listings-nextpagetoken]

`GET /v1/listings` returns the ids of the listings, most recently created first, and an additive summary of the same listings.

```bash
curl "https://api.athaus.ai/v1/listings?limit=2" \
  -H "Authorization: Bearer ath_live_..."
```

```json
{
  "externalListingIds": ["WE-12", "WE-14"],
  "nextPageToken": "eyJzIjoiMjAyNi0xMS0xMVQwOTozMDowMFoifQ",
  "listings": [
    {
      "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
      "externalListingId": "WE-12",
      "status": "active",
      "updatedAt": "2026-11-11T09:30:00Z"
    },
    {
      "listingId": "0190f39e-52a0-7d13-b6c4-8e1f0a9d7c25",
      "externalListingId": "WE-14",
      "status": "draft",
      "updatedAt": "2026-11-10T16:02:41Z"
    }
  ]
}
```

The next page:

```bash
curl "https://api.athaus.ai/v1/listings?limit=2&nextPageToken=eyJzIjoiMjAyNi0xMS0xMVQwOTozMDowMFoifQ" \
  -H "Authorization: Bearer ath_live_..."
```

On the last page `nextPageToken` is `null`.

| Parameter                                | Effect                                                                                        |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| `limit`                                  | entries per page, 1 to 100, default 50. More than 100 is a `400`, it is never silently capped |
| `nextPageToken`                          | the value from the previous page                                                              |
| `updatedSince`                           | only listings changed since this instant (ISO 8601)                                           |
| `status`                                 | `draft`, `active`, `paused`, `reserved` or `closed`                                           |
| `distributionType`, `city`, `postalcode` | filters on the listing                                                                        |

## Other resources: cursor [#other-resources-cursor]

Contacts, inquiries, viewings, files, proposals, events and webhook endpoints return a list object.

```bash
curl "https://api.athaus.ai/v1/contacts?limit=2" \
  -H "Authorization: Bearer ath_live_..."
```

```json
{
  "object": "list",
  "data": [
    { "object": "contact", "id": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17" },
    { "object": "contact", "id": "0190f39e-52a0-7d13-b6c4-8e1f0a9d7c25" }
  ],
  "hasMore": true,
  "nextCursor": "eyJzIjoiLWNyZWF0ZWRBdCIs..."
}
```

`data` is cut to the `id` here, every object has all its fields. Send `nextCursor` as `cursor` to get the next page. On the last page `hasMore` is `false` and `nextCursor` is `null`.

| Parameter      | Effect                                                                                       |
| -------------- | -------------------------------------------------------------------------------------------- |
| `limit`        | entries per page, 1 to 100, default 50                                                       |
| `cursor`       | the value from `nextCursor` of the previous page                                             |
| `updatedSince` | only objects changed since this instant (ISO 8601)                                           |
| `sort`         | `createdAt`, `-createdAt` (default), `updatedAt` or `-updatedAt`. The minus sorts descending |

Filters such as `city` or `status` are on the page of the operation in the [reference](/en/api/v1/referenz). Events have no `sort` and no `updatedSince`: see [Events](/en/api/v1/ereignisse).

## Follow changes [#follow-changes]

If you only want to know what changed since your last fetch, send the instant of your last fetch as `updatedSince`:

```bash
curl "https://api.athaus.ai/v1/contacts?sort=updatedAt&updatedSince=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer ath_live_..."
```

## What you should know [#what-you-should-know]

* **There is no total count.** It would cost a second query over the whole stock on every page. Read until the last page.
* **A token and a cursor are opaque.** Send them back unchanged, do not take them apart. Their content may change without that being a break.
* **A cursor belongs to its sort order.** If you change `sort` in the middle of paging, the API answers `400` with `invalid_query`. Start again with the first page.
* **There is no offset.** An offset shifts as soon as somebody creates something between two fetches.
