Paging through a list
How to read a long list from the Modbot API one page at a time.
Most lists in the Modbot API are too long to send in one answer, so they come back a page at a time.
Ask for a page
Ask for the first page, or any other, with page and pageSize:
curl -H "Authorization: Bearer mbk_..." \
"https://modbot.example.com/api/members?page=1&pageSize=50"The answer carries the rows and three numbers:
{
"members": [ ... ],
"total": 4812,
"page": 1,
"pageSize": 50
}totalis how many rows match your filters, across every page.pageis the page you asked for.pageSizeis how many rows a page holds — what you asked for, held inside what the endpoint will serve.
How many pages there are is total divided by pageSize, rounded up. To read a whole list, count
up to that.
curl -H "Authorization: Bearer mbk_..." \
"https://modbot.example.com/api/members?page=2&pageSize=50"Pages count from 1. A page past the end of the list comes back with no rows and the same
total, not an error. A page number of 0 or less is the first page.
Send the same filters, search and sort with every page. A page number says how far into a list you are; it does not remember which list.
What a page number can get wrong
These lists are being written to while you read them. The member sweep finishes, somebody is banned, the Discord bot reads the whole member list again.
"Skip 50 rows and give me the next 50" is counted from wherever the list starts at the moment you ask. So:
- Somebody joins while you are between page one and page two. Everything shifts down one, and the last person on page one is now the first person on page two. You read them twice.
- Somebody leaves instead. Everything shifts up one. One person is not on any page you read.
Neither is visible in the answer. If you are reading a whole list to compare it with your own copy, read it by id afterwards rather than trusting that every row appeared exactly once, or read it at a quiet moment.
What cannot happen is two rows swapping places on a list that is not being written to: every sort these lists offer ends in the person's id, which is unique, so tied rows always come back in the same order.
Which lists page which way
| Endpoint | How it pages |
|---|---|
GET /api/members | page and pageSize |
GET /api/bans | page and pageSize |
GET /api/discord/members | page and pageSize |
GET /api/people | page and pageSize |
GET /api/discord/members/{id}/messages | page and pageSize, or at with a message id for the page holding it |
GET /api/repeat-offenders | offset and limit |
GET /api/audit/bans | offset and limit |
GET /api/cases | offset and limit |
GET /api/audit | beforeOccurredAt and beforeId, sent back together from the last answer |
GET /api/logs | before, the last row id from the last answer |
GET /api/events/poll | cursor, the one from the last answer — see long polling |
GET /api/live/poll | after, the cursor from the last answer — see live updates |
GET /api/discord/bans | page and pageSize |
GET /api/giveaways/{id}/draws/{drawId}/entrants | page and pageSize |
GET /api/requests | page and pageSize. VRChat sends no total, so there is no total: hasMore is true when the page came back full |
GET /api/group/posts | page and pageSize, at most 100 a page. total is VRChat's count |
GET /api/group/invites | page and pageSize, at most 100 a page, with hasMore instead of total |
GET /api/group/gallery | page and pageSize, at most 100 a page, with hasMore instead of total |
GET /api/settings/ai/calls | skip, how many rows to skip. Send the next from the last answer; it is null on the last page |
GET /api/insights | before, the time the last insight you were shown was made, with limit |
The audit log and Modbot's own log page from the last row you were shown rather than by number,
because both are far too big to count on every request and neither has a total to work a page
count out of. For those two, keep sending what the last answer gave you until it gives you nothing.
Lists that stop at a limit
The lists not named above have no pages. Some are short enough to come back whole. These stop at a limit, and the answer does not say when there was more: a list that comes back with exactly that many rows may have had more.
| Endpoint | Returns at most | Which ones |
|---|---|---|
GET /api/moderation-flags | 200 | The newest flags |
GET /api/reviews | 500 | The oldest open reviews, or the most recently closed |
GET /api/evidence | 500 | The newest items |
GET /api/giveaways | 500 | The latest to close |
GET /api/notifications | 50 | The newest notifications |
GET /api/chat | 100 | The newest conversations |
GET /api/webhooks/{id}/deliveries | 50 | The latest attempts |
GET /api/imports | 50 | The latest imports |
GET /api/notes | limit: default 50, at most 200 | The newest notes |
GET /api/alerts | limit: default 20, at most 100 | The newest alerts |
A limit above its maximum is lowered to the maximum rather than refused.
In the web app
The page you are on is part of the address, beside the filters. A link you copy from the member list opens on the page you were looking at, refreshing keeps you there, and the browser's Back button undoes a page turn rather than leaving the screen.