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.

本頁內容

List endpoints in the API return data in pages. The platform has historically used two pagination schemes; the specific scheme is documented on each endpoint in the interactive reference.

Scheme 1: offset and X-Total-Count

Classic offset-based pagination. The request accepts the limit query parameter (page size) and offset (how many records to skip):

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

The total record count is returned in the X-Total-Count response header. Use it to calculate the number of pages: keep incrementing offset by limit while offset is less than the X-Total-Count value. 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 mbp_YOUR_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