Skip to main content

​
How It Works

The API v2 uses cursor-based pagination for all list endpoints. Cursors are opaque, base64-encoded strings — treat them as opaque tokens and do not attempt to decode or construct them.

​
Query Parameters

ParameterTypeDefaultDescription
cursorstring—Opaque cursor from a previous response. Omit to start from the beginning.
limitinteger20Number of items per page. Range: 1–100.

​
Response Shape

All paginated responses follow this structure: 
{
  "data": [...],
  "pagination": {
    "cursor": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==",
    "hasMore": true,
    "total": 142
  }
}
FieldTypeDescription
dataarrayThe page of results.
pagination.cursorstring | nullCursor to pass for the next page. null when there are no more results.
pagination.hasMorebooleantrue if more results are available beyond this page.
pagination.totalintegerTotal number of items matching the query.

​
Paginating Through All Results

Pass the cursor from each response into the next request to iterate through all pages: 
async function fetchAllConversations(agentId, apiKey) {
  const conversations = [];
  let cursor = undefined;

  do {
    const params = new URLSearchParams({ limit: "100" });
    if (cursor) params.set("cursor", cursor);

    const response = await fetch(
      `https://www.chatbase.co/api/v2/agents/${agentId}/conversations?${params}`,
      {
        headers: { Authorization: `Bearer ${apiKey}` },
      }
    );

    const { data, pagination } = await response.json();
    conversations.push(...data);
    cursor = pagination.cursor;
  } while (cursor);

  return conversations;
}

​
Export Pagination

The export endpoint (GET /api/v2/agents/{agentId}/conversations/export) paginates through all conversations (from every source) with full message history included. Each page returns up to limit conversations with their complete messages already embedded — no separate call to a messages endpoint is needed.
Because each exported conversation includes all of its messages, pages can be significantly larger than other paginated responses. Use a smaller limit if you want to keep response sizes manageable.

​
Message Pagination

The messages endpoint (GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages) paginates backward from the newest messages. Within each page, messages are returned in chronological order. This means:
  • The first page contains the most recent messages
  • Passing the cursor fetches the next older page
  • Each page’s messages are ordered oldest → newest
The cursor returned by the Get a conversation endpoint is compatible with the messages endpoint, so you can use it to fetch older messages beyond what the conversation response includes.