Returns the message history of a room of any type, with cursor-based pagination. Hidden system messages are excluded.
When the Allow Anonymous Read (Accounts_AllowAnonymousRead) setting is enabled, public channels can be read without authentication.
This endpoint replaces the deprecated loadHistory, loadNextMessages, and loadSurroundingMessages Realtime API methods, which remain available until 9.0.0.
Permission required: preview-c-room (only to read a public channel you have not joined)
Changelog
| Version | Description |
|---|---|
| 8.9.0 | Added |
The authToken of the authenticated user.
The userId of the authenticated user.
The room ID. You must have access to the room.
The number of messages to return. The default is 20. The value is capped by the Max Record Amount (API_Upper_Count_Limit) setting.
The cursor.previous value from a previous response. Returns the messages older than that position. If cursor.previous is null, there are no older messages. Cannot be combined with next or aroundId.
The cursor.next value from a previous response. Returns the messages newer than that position. If cursor.next is null, there are no newer messages. Cannot be combined with previous or aroundId.
The ID of a message in the room. It loads messages centered around that message, including the message itself. Use it to jump to a specific message, such as a quoted message or a search result. Cannot be combined with next or previous.
An ISO 8601 date-time for the user's last-read position. It does not limit the returned messages. When the oldest returned message is newer than this value, the response includes firstUnread and unreadNotLoaded.
Whether to include thread replies that were not also sent to the room. The default is true.
OK
{
"messages": [
{
"_id": "Xq8sLpW3nZr2TmKeA",
"rid": "6GFJ3tbmHiyHbahmC",
"msg": "The release checklist is ready for review.",
"ts": "2026-09-23T10:05:00.000Z",
"u": {
"_id": "rbAXPnMktTFbNpwtJ",
"username": "dana.reyes",
"name": "Dana Reyes"
},
"_updatedAt": "2026-09-23T10:05:00.000Z",
"mentions": [],
"channels": []
},
{
"_id": "Bv5nTq7RkWz3YpLcD",
"rid": "6GFJ3tbmHiyHbahmC",
"msg": "Thanks, I will take a look this afternoon.",
"ts": "2026-09-23T10:00:00.000Z",
"u": {
"_id": "kP3wQz8LmNvT5rXyB",
"username": "sam.okafor",
"name": "Sam Okafor"
},
"_updatedAt": "2026-09-23T10:00:00.000Z",
"mentions": [],
"channels": []
}
],
"cursor": {
"next": null,
"previous": "1790157600000"
},
"unreadNotLoaded": 0,
"success": true
}The messages, ordered newest first.
The cursor for newer messages, or null if there are none.
The cursor for older messages, or null if there are none.
The oldest unread message that was not loaded in this response. Returned only when lastSeen is provided and unread messages exist beyond the returned messages.
The number of unread messages newer than lastSeen that were not loaded in this response.
Bad Request
{
"success": false,
"error": "Only one of \"next\", \"previous\" and \"aroundId\" can be provided [error-cursor-conflict]",
"errorType": "error-cursor-conflict"
}{
"success": false,
"error": "Invalid pagination cursor [error-invalid-cursor]",
"errorType": "error-invalid-cursor"
}Unauthorized
{
"status": "error",
"message": "You must be logged in to do this."
}Forbidden. You cannot access the room, or the room is a public channel that you have not joined and you do not have the preview-c-room permission.
{
"success": false,
"error": "unauthorized"
}Not Found. The room does not exist, or the message in aroundId is not a visible message in the room.
{
"success": false,
"error": "Resource not found"
}