Pagination

Most list endpoints return a page envelope:

1
{
2
  "data": [ /* … up to `limit` items … */ ],
3
  "next_cursor": "eyJvIjoyNX0",
4
  "total_count": 143
5
}

• data — the items in this page.
• next_cursor — pass this back as ?cursor= to fetch the next page. When it is null, you’ve reached the end.
• total_count — the total number of items matching your query across all pages, so you can show a count or compute the number of pages up front. It reflects your filters, and is the same on every page.

Paging through results

Request the first page, then keep passing next_cursor back as cursor until it’s null:

$
# First page
$
curl "https://api.usglobalmail.com/v1/mails?limit=50" \
>
  -H "Authorization: Bearer $USGM_API_KEY"
$
$
# Next page
$
curl "https://api.usglobalmail.com/v1/mails?limit=50&cursor=eyJvIjoyNX0" \
>
  -H "Authorization: Bearer $USGM_API_KEY"

The SDKs handle this for you — list methods return an iterator that fetches pages transparently:

1
for await (const mail of usgm.mails.list({ limit: 50 })) {
2
  console.log(mail.id);
3
}

Limit

Cursors are opaque and scoped

Treat next_cursor as an opaque token — don’t parse, build, or modify it. Each cursor is signed and bound to the exact endpoint and query it came from, so:

• Keep the other query parameters identical while paging. Changing a filter (or using the cursor on a different endpoint) invalidates it — the request fails with a 422 validation_error.
• Only pass back a next_cursor you actually received; a hand-crafted or altered cursor is rejected.

Maximum depth

Pagination reaches the first 10,000 items of a result set. Past that, next_cursor is null even when more rows exist (and a too-deep cursor returns 422). Use total_count to detect this, and narrow with filters (date range, status, folder, …) to reach items deeper than the limit rather than paging through everything.