The IllumiChat API provides two pagination patterns depending on the endpoint and the nature of the data being returned. Offset-based pagination is used for static collections such as workspaces, assistants, and members. Cursor-based pagination is used for streaming or append-heavy data such as messages and webhook deliveries.
Offset-based pagination uses limit and offset query parameters to control which slice of results is returned.
| Parameter | Type | Default | Description |
|---|
limit | integer | 25 | Number of items to return. Minimum 1, maximum 100. |
offset | integer | 0 | Number of items to skip before starting to return results. |
Response Shape
Every offset-paginated response includes the following top-level fields:
{
"data": [
{ "id": "ws_abc123", "name": "Acme Corp" },
{ "id": "ws_def456", "name": "Globex" }
],
"total": 48,
"limit": 25,
"offset": 0
}
| Field | Type | Description |
|---|
data | array | The requested items for the current page. |
total | integer | Total number of items matching the query across all pages. |
limit | integer | The limit that was applied. |
offset | integer | The offset that was applied. |
Examples
curl -X GET "https://beta.illumichat.com/api/workspaces?limit=10&offset=20" \
-H "Authorization: Bearer <your-api-key>"
To iterate through all pages, increment offset by limit on each request until offset >= total.
Iterating Through All Pages
async function fetchAll(baseUrl, token) {
const items = [];
let offset = 0;
const limit = 100;
while (true) {
const res = await fetch(`${baseUrl}?limit=${limit}&offset=${offset}`, {
headers: { Authorization: `Bearer ${token}` },
});
const { data, total } = await res.json();
items.push(...data);
offset += limit;
if (offset >= total) break;
}
return items;
}
Cursor-based pagination uses an opaque cursor parameter and returns a nextCursor value. This pattern is more efficient for large, frequently changing datasets because it avoids the consistency issues inherent in offset-based pagination.
| Parameter | Type | Default | Description |
|---|
limit | integer | 25 | Number of items to return. Minimum 1, maximum 100. |
cursor | string | null | Opaque cursor from a previous response. Omit to start from the beginning. |
Response Shape
{
"data": [
{ "id": "msg_aaa111", "content": "Hello" },
{ "id": "msg_bbb222", "content": "Hi there" }
],
"nextCursor": "eyJpZCI6Im1zZ19iYmIyMjIifQ==",
"hasMore": true
}
| Field | Type | Description |
|---|
data | array | The requested items for the current page. |
nextCursor | string or null | Pass this value as the cursor parameter to fetch the next page. null when there are no more results. |
hasMore | boolean | true if additional pages exist beyond the current result set. |
Examples
# First page
curl -X GET "https://beta.illumichat.com/api/conversations/conv_abc/messages?limit=50" \
-H "Authorization: Bearer <your-api-key>"
# Next page
curl -X GET "https://beta.illumichat.com/api/conversations/conv_abc/messages?limit=50&cursor=eyJpZCI6Im1zZ19iYmIyMjIifQ==" \
-H "Authorization: Bearer <your-api-key>"
Cursor values are opaque and may change between API versions. Do not parse, construct, or store cursors for long-term use. Always obtain a fresh cursor from the most recent API response.
Choosing a Pattern
| Use Case | Pattern | Reason |
|---|
| Listing workspaces, assistants, members | Offset-based | Stable datasets; total count is useful for UI |
| Browsing messages in a conversation | Cursor-based | Append-heavy data; avoids skipped or duplicated items |
| Webhook delivery logs | Cursor-based | High-volume, time-ordered data |
| Search results | Offset-based | Users expect page numbers and total counts |
If an endpoint supports pagination, the documentation for that endpoint specifies which pattern is used. When in doubt, check the response shape: the presence of nextCursor indicates cursor-based pagination, while total and offset indicate offset-based pagination.
