Modbot Docs
API

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
}
  • total is how many rows match your filters, across every page.
  • page is the page you asked for.
  • pageSize is 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

EndpointHow it pages
GET /api/memberspage and pageSize
GET /api/banspage and pageSize
GET /api/discord/memberspage and pageSize
GET /api/peoplepage and pageSize
GET /api/discord/members/{id}/messagespage and pageSize, or at with a message id for the page holding it
GET /api/repeat-offendersoffset and limit
GET /api/audit/bansoffset and limit
GET /api/casesoffset and limit
GET /api/auditbeforeOccurredAt and beforeId, sent back together from the last answer
GET /api/logsbefore, the last row id from the last answer
GET /api/events/pollcursor, the one from the last answer — see long polling
GET /api/live/pollafter, the cursor from the last answer — see live updates
GET /api/discord/banspage and pageSize
GET /api/giveaways/{id}/draws/{drawId}/entrantspage and pageSize
GET /api/requestspage and pageSize. VRChat sends no total, so there is no total: hasMore is true when the page came back full
GET /api/group/postspage and pageSize, at most 100 a page. total is VRChat's count
GET /api/group/invitespage and pageSize, at most 100 a page, with hasMore instead of total
GET /api/group/gallerypage and pageSize, at most 100 a page, with hasMore instead of total
GET /api/settings/ai/callsskip, how many rows to skip. Send the next from the last answer; it is null on the last page
GET /api/insightsbefore, 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.

EndpointReturns at mostWhich ones
GET /api/moderation-flags200The newest flags
GET /api/reviews500The oldest open reviews, or the most recently closed
GET /api/evidence500The newest items
GET /api/giveaways500The latest to close
GET /api/notifications50The newest notifications
GET /api/chat100The newest conversations
GET /api/webhooks/{id}/deliveries50The latest attempts
GET /api/imports50The latest imports
GET /api/noteslimit: default 50, at most 200The newest notes
GET /api/alertslimit: default 20, at most 100The 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.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page