Show Count Badges

The public API does not return exact total counts for list endpoints. For count badges such as “open conversations” or “unread conversations”, request one bounded page and show a plus sign when more results are available.

A common pattern is to request up to 50 records:

curl "https://api.getmateo.com/v1/conversations?status=open&limit=50" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 2026-07-01"

Example response, abbreviated:

{
  "object": "list",
  "data": [
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
      "status": "open",
      "unread": true,
    },
  ],
  "next_page_url": "/v1/conversations?status=open&limit=50&page_token=<opaque_page_token>",
  "previous_page_url": null,
}

Use data.length for the visible count. Treat next_page_url as the has-more signal: if it is present, more matches exist, so show the count as 50+. If next_page_url is null, show the exact number returned in data.length.

const count = response.data.length;
const label = response.next_page_url ? `${count}+` : String(count);

Show unread conversations

Apply the same pattern to any supported filter:

curl "https://api.getmateo.com/v1/conversations?status=open&unread=true&limit=50" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 2026-07-01"

When you need the list too

If your UI shows the matching conversations, use the same response for the first page of the list and paginate with next_page_url when the user asks for more.

For a continuously updated external inbox, maintain your own projection from conversation changes and reconcile it with paginated list requests instead of polling every unread conversation page.

See Pagination for the shared list response shape and pagination rules.