LidmeoDevelopers

Pagination

Reading a list page by page, with a cursor, and rereading only what changed.

Every list answers the same way:

{
  "object": "list",
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "cur_eyJ2IjoxLCJpZCI6NDgyMTN9"
}
  • limit: the number of items per page, from 1 to 100 (25 by default).
  • starting_after: the next_cursor of the previous page, to read the next one.
  • has_more: false on the last page, where next_cursor is null.

A page can hold fewer items than limit, even none, without being the last: when a filter sets many prospects aside, Lidmeo returns what it examined and a cursor for the rest. Keep going while has_more is true, never based on the number of items.

Short lists (GET /v1/campaigns, GET /v1/stages, GET /v1/lists, GET /v1/webhook_endpoints) come back whole: they take neither limit nor starting_after, and their has_more is false.

A cursor is opaque: don't read it, don't build it, keep it as it is. It starts with cur_, or it is the id of the last item returned (evt_… for events). A damaged cursor answers 400 invalid_request (field query.starting_after): start again from the first page. There is no pagination by page number: an item added while you read does not shift the following pages.

A parameter the route does not know is never ignored: it answers 400 invalid_request, with the code unknown_parameter and the field query.<name>. So limit sent to a short list is refused.

curl "https://api.lidmeo.com/v1/prospects?limit=100&starting_after=cur_eyJ2IjoxLCJpZCI6NDgyMTN9" \
  -H "Authorization: Bearer $LIDMEO_API_KEY"

The SDKs go through the pages for you:

for await (const prospect of lidmeo.paginate((q) => lidmeo.prospects.list({ ...q, limit: 100 }))) {
  console.log(prospect.full_name);
}

Rereading only what changed

updated_since (an ISO 8601 date with its time zone, for example 2026-10-01T08:00:00+02:00; a day alone starts at midnight, Paris time) keeps only what changed since, on GET /v1/prospects and GET /v1/conversations. Keep the time of your last read, and start from there.

  • On prospects, it is a change of the prospect record itself: adding or removing a list, linking an external id or renaming a stage does not bring it back.
  • On conversations, it is the last message, at or after that date.
  • With a view (view) or the search, it does not combine: 400 invalid_request.

To follow changes as they happen, events are made for it.

A very long list

When a computed view ("À répondre", "À relancer"…) holds more items than Lidmeo scans at once, the response carries truncated: true: narrow it, for example with campaign, to see the others. A list is never cut silently.

On this page