Pagination

How it works

GET /v1/messages?limit=50

{
  "data": [ … 50 messages, newest first … ],
  "hasMore": true,
  "nextCursor": "msg_AZLm3kQ8T2Sf9pXbNc7HrQ"
}

GET /v1/messages?limit=50&before=msg_AZLm3kQ8T2Sf9pXbNc7HrQ

Keyset rather than OFFSET for two reasons. Offset gets slower the deeper you page, and on a table that grows by every send it also skips and repeats rows when new messages arrive mid-scan — quiet duplicates that nothing about the result would reveal. The cursor compares the (created_at, id) pair, so a hundred messages written in the same millisecond page correctly rather than all but one being skipped at the boundary.

Check both signals, and neither on its own

Two endpoints break the obvious loop, in opposite directions. Whichever single field you pick as your stopping rule, one of them defeats it — so the correct loop reads both, and the two paragraphs below are why.

import { Posthaste } from '@posthaste/sdk'

const posthaste = new Posthaste({ apiKey: process.env.POSTHASTE_KEY })

// One page, exactly as the endpoint returns it.
const page = await posthaste.messages.list({ limit: 50, status: 'bounced' })
page.data        // MessageSummary[]
page.hasMore     // sent by this endpoint; authoritative where it is sent
page.nextCursor  // pass as `before` on the next request

// Every page. autoPaginate consults both signals for you, so both traps below
// are closed by construction — it also stops on an empty page and on a cursor
// that fails to advance.
for await (const message of posthaste.messages.autoPaginate({ status: 'bounced' })) {
  await suppress(message.to)
}

// Or collect, with a ceiling you choose rather than an unbounded drain.
const recent = await posthaste.messages.listAll({ status: 'bounced' }, 500)

// Every list has the same three methods, including the ones that send no
// hasMore. This is all sixty invoices, not the first fifty.
const invoices = await posthaste.billing.listAllInvoices()

for await (const key of posthaste.apiKeys.autoPaginate()) {
  await audit(key)
}

// Billing history pages by `after` and reads oldest first. The helper knows.
for await (const event of posthaste.billing.autoPaginateHistory()) {
  await record(event.seq, event.type)
}

Checking both — stop when hasMore is explicitly false, or when the cursor is null — costs nothing and is correct against every endpoint, present and future. Each check is the only correct stop on some endpoint, and each is wrong on its own somewhere else. The TypeScript SDK does exactly that inside autoPaginate, so there is no loop to get wrong.

Every list paginates

There is no longer any endpoint that returns a list whole. What differs between them is the page size, whether hasMore is sent, and — on one endpoint — the name and meaning of the cursor.

/v1/billing/history is the exception

It is the one list on the API that reads forward, and it does not use before at all. Both differences follow from what it is: the billing history is a hash chain, a chain is verified from its start, and a record that renders in a different order than it verifies in is a record people stop trusting. So the events come back oldest first, and you resume with after.

GET /v1/billing/history?limit=100

{
  "chain": { "valid": true, "brokenAt": null, "reason": null },
  "nextCursor": "100",
  "data": [ … 100 events, OLDEST first, seq 1 … 100 … ]
}

# "100" is a sequence number, not an id. Read it forward:
GET /v1/billing/history?limit=100&after=100

nextCursor is that sequence number rendered as a string, so passing it straight back as after is correct — and it is null on the last page, which is the stopping condition since there is no hasMore here either. Passing an id rather than a number is refused with 400 invalid_request.

chain travels with every page and is the verification of the whole account history, not of the page you are holding — so it means the same thing on page four as on page one, and paging through the record does not weaken the guarantee it makes.

What a cursor guarantees

Rows are ordered newest first, and a cursor is a position in that order — so a page you fetch after new rows have arrived does not shift under you, because the new rows sort ahead of where you are reading. Walking a list to its end therefore gives you a consistent snapshot backwards in time, not a consistent snapshot of the whole list.

/v1/billing/history reads the other way, and gains something for it: because it walks forward from a sequence number, new events land ahead of your cursor rather than behind it. Resuming from the last seq you processed picks up everything since, which is what makes it the one list you can poll incrementally without re-reading what you already have.

Cursors are just ids — or, on the billing history, sequence numbers — and do not expire. Storing one to resume a sync later is a legitimate use: pass the newest id you have already processed as before when you resume, or filter on from if you would rather bound by time.