Skip to content

Pagination and filtering

URL shape

All resource endpoints are org-scoped: /api/v1/orgs/{org_id}/{resource}. The connections endpoint is the exception — it lists ALL of your app's connections across orgs at /api/v1/connections. See the connections guide for that endpoint.

Accounts and tax rates are also exceptions: those two endpoints return the entire active list in one response and accept no limit/offset at all — there's no per-org volume of either that makes pagination worth the extra round trips. Every other org-scoped list endpoint (bills, invoices, credit notes, contacts) uses the same limit/offset shape:

GET /api/v1/orgs/{org_id}/bills?limit=50&offset=100

{
  "items": [ /* … */ ],
  "count": 342,
  "limit": 50,
  "offset": 100
}
  • limit and offset are both non-negative integers; an invalid or negative value is invalid_pagination_params (400). limit is silently clamped to each endpoint's max, not rejected — see the per-resource default/max table in Hard limits.
  • count is the total number of matching rows, not the number returned in items — use it to know when you've reached the end (offset + len(items) >= count).
  • There is no opaque cursor: offset is a plain integer you compute yourself. Offset pagination is not stable under concurrent writes: the underlying query is re-run on every page, ordered by a mutable column (updated_at for bills, invoices and credit notes; display_name for contacts), so a row changed between two page requests can move in the sort order and rows can be skipped or returned twice. Prefer modified_since (below) for a stable incremental sync instead of paging through everything on every run.

Incremental sync with modified_since

Most read endpoints accept:

GET /api/v1/orgs/{org_id}/bills?modified_since=2026-09-01T00:00:00Z

An invalid (non-ISO-8601) value is invalid_modified_since (400). Combine with limit/offset as normal — modified_since narrows the result set, it doesn't change the pagination shape.

Per-resource filters

Beyond limit/offset/modified_since, individual resources accept their own query filters (status, contact, date range, …) — see each operation's parameters in the API reference rather than a second copy of the list here.