AthausDocs

REST API: pagination

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.

Last updated:

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

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

curl "https://api.athaus.ai/v1/listings?limit=2" \
  -H "Authorization: Bearer ath_live_..."
{
  "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:

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

On the last page nextPageToken is null.

ParameterEffect
limitentries per page, 1 to 100, default 50. More than 100 is a 400, it is never silently capped
nextPageTokenthe value from the previous page
updatedSinceonly listings changed since this instant (ISO 8601)
statusdraft, active, paused, reserved or closed
distributionType, city, postalcodefilters on the listing

Other resources: cursor

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

curl "https://api.athaus.ai/v1/contacts?limit=2" \
  -H "Authorization: Bearer ath_live_..."
{
  "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.

ParameterEffect
limitentries per page, 1 to 100, default 50
cursorthe value from nextCursor of the previous page
updatedSinceonly objects changed since this instant (ISO 8601)
sortcreatedAt, -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. Events have no sort and no updatedSince: see Events.

Follow changes

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

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

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.

Keep reading

On this page