Pagination
Every list endpoint pages the same way — a cursor token, a consistent envelope, and newest-first ordering by default.
Every list endpoint paginates with an opaque cursor, and they all share one envelope shape — so pagination code is written once and reused across inboxes, threads, and API keys.
Request parameters
| Parameter | Type | Default | Notes |
|---|---|---|---|
limit | integer | 50 | Page size, 1–100. |
page_token | string | — | The next_page_token from the previous page. Omit for the first page. |
ascending | boolean | false | Sort oldest-first when true. Default is newest-first. |
Response envelope
Every list response carries the same three pagination fields, plus a typed array
named for the resource (inboxes, threads, api_keys, …):
| Field | Type | Notes |
|---|---|---|
count | integer | Number of items in this page. |
limit | integer | The page size that was applied. |
next_page_token | string | null | Token for the next page, or null when there are no more. |
<resource> | array | The page of items — e.g. inboxes. |
{
"count": 2,
"limit": 2,
"next_page_token": "eyJvZmZzZXQiOjJ9",
"inboxes": [
{ "inbox_id": "inb_8f2a1c9d", "email": "brave-otter@agents.theinboxagents.com" },
{ "inbox_id": "inb_2a7b4e11", "email": "keen-finch@agents.theinboxagents.com" }
]
}Ordering
Lists come back newest-first by default (created_at / last_activity_at
descending). Pass ascending=true for oldest-first. Search-style listings cap
limit at 100.
Iterating every page
Follow next_page_token until it comes back null:
# First page
curl "https://app.theinboxagents.com/api/v1/inboxes?limit=50" \
-H "Authorization: Bearer $INBOXAGENTS_API_KEY"
# Next page — pass the previous response's next_page_token
curl "https://app.theinboxagents.com/api/v1/inboxes?limit=50&page_token=eyJvZmZzZXQiOjUwfQ" \
-H "Authorization: Bearer $INBOXAGENTS_API_KEY"async function* allInboxes() {
let pageToken: string | undefined;
do {
const url = new URL("https://app.theinboxagents.com/api/v1/inboxes");
url.searchParams.set("limit", "50");
if (pageToken) url.searchParams.set("page_token", pageToken);
const page = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.INBOXAGENTS_API_KEY}` },
}).then((r) => r.json());
yield* page.inboxes;
pageToken = page.next_page_token ?? undefined;
} while (pageToken);
}
for await (const inbox of allInboxes()) {
console.log(inbox.email);
}def all_inboxes():
base = "https://app.theinboxagents.com/api/v1"
auth = {"Authorization": f"Bearer {os.environ['INBOXAGENTS_API_KEY']}"}
page_token = None
while True:
params = {"limit": 50}
if page_token:
params["page_token"] = page_token
page = requests.get(f"{base}/inboxes", headers=auth, params=params).json()
yield from page["inboxes"]
page_token = page.get("next_page_token")
if not page_token:
break
for inbox in all_inboxes():
print(inbox["email"])# The CLI handles paging for you when listing
inboxagents inboxes list --limit 50The typed SDKs wrap this loop in a pagination helper, so you can iterate results
directly without ever handling a page_token yourself.