Pagination

Every list in the Chat API pages with a cursor. You ask for a page, and each answer tells you how to ask for the next one. There are no page numbers and no offsets.

How a page works

A list answers with items and next_cursor:

{ "items": [ { "message_id": "m-102" } ], "next_cursor": "m-102" }

To get the next, older page, send the cursor back as before:

GET .../conversations/{conversation_id}/messages?limit=50&before=m-102

Newest first. Page one holds the newest items, and before moves back in time.
A null cursor ends the list. On the last page next_cursor is null. Stop there.
Pass the cursor back unchanged. Treat it as an opaque string. Do not build one yourself.
Stable order. Items that share a timestamp keep a fixed order.

Limit

limit is optional. The default is 50 items and the maximum is 100 items. A larger value is capped to the maximum, not rejected.

What is ordered how

List	Order
Messages	Newest message first
Conversations	Most recent activity first
Members	Most recently added first

Administration lists, such as the audit log and moderation of conversations, page the same way.

Errors

Status	Code	Cause
400	`invalid_limit`	`limit` is not a positive integer
400	`invalid_cursor`	`before` is not a cursor this list issued

A cursor belongs to the list it came from. A message cursor works for the messages of the same conversation, and nothing else. Drop before to start again from the newest item.

Reading everything

The SDKs return next_cursor as is. A loop reads every page:

import { ChatClient, type ChatMessage } from '@central-code-station/ccs-chat-client';

// Reads a whole conversation, newest first, one page at a time.
export async function readAllMessages(chat: ChatClient, conversationId: string): Promise<ChatMessage[]> {
  const all: ChatMessage[] = [];
  let before: string | undefined;
  do {
    const page = await chat.messages.list(conversationId, { before, limit: 100 });
    all.push(...page.items);
    before = page.next_cursor ?? undefined; // null on the last page
  } while (before);
  return all;
}

Most apps need only the first page, and fetch older ones as the user scrolls back.