Pagination

Cursor pages

Lists take limit and cursor, and answer with data, has_more and next_cursor. Pass next_cursor as cursor for the next page; the last page has no next_cursor. limit defaults to 50 and is at most 200. The examples are Ciresk CI's job list.

curl -s "$CIRESK_API/v1/ci/jobs?limit=50" -H "Authorization: Bearer $CIRESK_KEY"

A cursor the list did not issue is 400 invalid_cursor: start again without one. In Ciresk CI, GET /v1/ci/jobs filters by repository, ref, actor and state. Test results (GET /v1/ci/jobs/{id}/tests) take the same cursor but answer tests, total, failed_total and next_cursor; they list failing and flaky tests by default, and every test with status=all.

Byte ranges

Some resources page by bytes rather than rows. Ciresk CI's log slices (GET /v1/ci/jobs/{id}/log) do: offset and limit in, byte_offset, byte_length, total_bytes, next_byte_offset and truncated out, at most 256 KiB per call and 64 KiB by default. task, failed_only, tail, grep and context narrow the slice before paging; every trimmed answer says so with truncated: true and a hint.