Pagination

Offset pagination

All list endpoints support offset pagination via page and per_page query parameters:

GET /api/v1/employers?page=2&per_page=50

Parameter	Default	Min	Max	Notes
page	1	1	—	1-indexed
per_page	25	1	100	Capped at 100 to protect the server

Per-endpoint defaults may vary — some smaller endpoints default to 25, others to 50. Check the resource reference.

Response headers

List endpoints include pagination metadata in response headers:

X-Total-Count: 287
X-Page: 2
X-Per-Page: 50
X-Total-Pages: 6

• X-Total-Count — total rows matching the query
• X-Page — the current page number
• X-Per-Page — rows per page
• X-Total-Pages — total pages available

You can iterate through all pages by stopping when X-Page == X-Total-Pages.

Example: fetching all employers

def fetch_all_employers
  all = []
  page = 1

  loop do
    response = api_get("/employers?page=#{page}&per_page=100")
    all.concat(response.body)

    total_pages = response.headers["X-Total-Pages"].to_i
    break if page >= total_pages

    page += 1
  end

  all
end

Response body

List endpoints return a plain JSON array at the top level (not wrapped in an envelope):

[
  { "id": 1, "legal_name": "Acme Pty Ltd", ... },
  { "id": 2, "legal_name": "Widgets Pty Ltd", ... },
  ...
]

The pagination metadata lives in headers, keeping the body compact and parseable by any JSON client.

Sorting

Most list endpoints have a sensible default sort (e.g. employers by legal name alphabetically, pay events by created_at descending). Explicit sort parameters will be added in a future version.

Filtering

Several list endpoints support filtering via query parameters:

/api/v1/pay_events

GET /api/v1/pay_events?employer_id=12&status=accepted

Available filters:
- employer_id — only return pay events for this employer
- status — one of draft, ready, submitted, accepted, rejected, error

/api/v1/submissions

GET /api/v1/submissions?employer_id=12&status=accepted

Available filters:
- employer_id
- status

/api/v1/employers/:id/employees

GET /api/v1/employers/12/employees?include_terminated=1

By default terminated employees are excluded. Pass include_terminated=1 to include them.

Cursor pagination (future)

High-volume customers may eventually need cursor-based pagination for stable iteration over large datasets. It's on the roadmap but not built yet — for now, offset pagination handles datasets up to roughly 10,000 rows comfortably. If you're routinely iterating larger sets, let us know at support@beeswaxapp.com.

Best practice

• Use reasonable per_page sizes. 100 is fine for one-off extracts. For user-facing UI, stick to 25–50.
• Don't page beyond X-Total-Pages. Beeswax returns an empty array for out-of-range pages, but it still counts against your rate limit.
• Cache pagination results. If you need to walk through the same list multiple times in a workflow, cache it locally rather than re-paginating.
• Filter server-side. Don't fetch all records and filter in your code — pass filter query params so the database does the work.