Pagination

GET /v1/company is the one operation that returns more than one record, and so the one that paginates. It offers two ways through a result set, and a request uses one or the other — sending both page and cursor is 422 validation_error.

• Random access: page (1-based) with page_size (up to 100) — a direct jump to a known page.

• Walking every match: leave cursor out of the first call, then repeat the same search parameters with cursor=<the previous response's next_cursor> until next_cursor comes back null. page_size may change between calls — a cursor is a position in the result set, not a page number, and a cursor page reports page: null.

The walk is the exhaustive form: a cursor resumes immediately after the last record it returned, so companies added to or removed from the datalake mid-walk neither skip nor repeat a record, which offsets cannot promise. A cursor belongs to the query that issued it: replaying one against a different search is 422 validation_error, and the first page is the way back. Cursors are opaque — a cursor is meaningful only to the API that issued it, and one that has been parsed, edited or constructed is not a valid cursor.

has_more and next_cursor are authoritative; total is best-effort (a floor when total_is_lower_bound is true), so stop on next_cursor, never on a count. Every page is one call and is billed as one.