قاعدة معرفة GetMyBot

Pagination

Two pagination schemes in the GetMyBot API — offset with X-Total-Count and cursor-based before with has_more — and the caps on limit and offset.

في هذه الصفحة

The API returns long lists, such as customers or messages, in smaller pages. Fetching the next page is called pagination. A program can then read the list without downloading its entire history at once.

There are two ways to continue: skip a number of records already read (offset), or pass a marker for the last position read (cursor). The method for each API endpoint is shown in the interactive reference.

Scheme 1: offset and X-Total-Count

The limit query parameter sets the page size, and offset is the number of records to skip. For example, limit=50&offset=100 requests up to 50 records after the first 100. Add these parameters after ? in the request URL:

curl -H "Authorization: Bearer <PERSONAL_TOKEN>" \
  "https://your-domain/api/bots/BOT_ID/users?limit=50&offset=100"

The X-Total-Count response header gives the total number of records. After each response, increase offset by the number of records actually returned until offset reaches X-Total-Count. The response body is an array of items on the current page.

The offset has a ceiling

"While offset is less than X-Total-Count" does not go on forever. An offset above 100,000 is refused with 400: on every endpoint that accepts an offset at all. The response says what to do: narrow the filter, or use cursor pagination.

This is not protection against a typo but protection for the database: an offset makes it produce and throw away every skipped row, so offset=5000000 is a full table scan for one page.

If a list is longer than 100,000 records, an offset will not reach the end of it. The options:

  • narrow the selection with the endpoint's filters (period, channel, status): usually enough;
  • switch to a cursor if the endpoint supports one (scheme 2 below; payment and collection-record lists, for instance, support both);
  • if you genuinely need the whole dataset, use the export of the relevant section instead of walking pages.

The page size cap differs per endpoint

There is no single maximum for limit: different lists use different ones: 200, 500 and 1000 all occur. The exact value is on the endpoint's page in the reference.

What endpoints do with an oversized limit also differs, and that matters more than the numbers:

  • some refuse the request with 400 and a message like "limit must be at most 500, got 5000";
  • others silently fall back to the default (usually 100) and return a smaller page than you asked for.

Hence the rule: never assume you received a page of the size you requested. Look at the length of the array you got, not at your own limit, and advance offset by the number of items actually returned. Otherwise, on an endpoint of the second kind, you advance by 5000 having received 100 and skip 98% of the data without ever seeing an error.

For the same reason, do not treat an empty page as the only sign of the end: use X-Total-Count and the actual item count together.

Scheme 2: cursor before and has_more

Cursor-based pagination for time-ordered feeds (for example, dialog messages). The request accepts limit and an optional before cursor: the identifier or marker of the last item already received:

curl -H "Authorization: Bearer <PERSONAL_TOKEN>" \
  "https://your-domain/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

The response contains a page of items and a has_more flag. While has_more is true, repeat the request passing the cursor of the last received item as before. When has_more is false, you have reached the last page.

Which scheme to use

You do not choose the scheme: the endpoint determines it. Reference-style lists typically use offset and X-Total-Count; time-ordered feeds use the before cursor and has_more. Always check the endpoint's page in the reference.

What's next