Pagination and rate limits

Cursors, not offsets

Search results page by opaque cursor. Each response carries `next_cursor`; pass it back as `cursor` to get the next page, and stop when it comes back null.

# page 1
curl -X POST https://api.truepoint.in/api/v1/public/search \
  -H "Authorization: Bearer $TRUEPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity":"company","filters":{"country":"IN"},"limit":25}'

# page 2 — same filters, plus the cursor from page 1
curl -X POST https://api.truepoint.in/api/v1/public/search \
  -H "Authorization: Bearer $TRUEPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity":"company","filters":{"country":"IN"},"limit":25,"cursor":"c2Vhcm5jaDo0Mg"}'

Offsets are not offered, and that is not an omission. The graph changes while you page: with an offset, a record inserted ahead of your position silently shifts every later page, so you skip rows and re-read others without ever being told. A cursor is a position in a stable ordering, so it does not have that failure mode.

Choosing a page size

`limit` accepts 1–100 and defaults to 25. Larger pages are cheaper per request, not per result — the credit cost is identical either way. Size the page to what you will actually use: fetching 100 to display 10 bills you for 100.

Rate limits

Limits are per API key and are about protecting the service, not about pricing — they are separate from your credit balance, and a free call like company matching is still rate-limited.

• Exceeding a limit returns 429 with a `Retry-After` header, in seconds.
• 429s are never billed, so a backoff loop cannot cost you credits.
• Retry with exponential backoff and jitter. Retrying immediately, in lockstep, is how a fleet of workers turns one limit breach into a sustained one.
• If you need a sustained ceiling above the default, that is a conversation rather than a config flag — the limit exists to keep one caller from degrading everyone.