Pagination guide

The Partner API uses four response shapes. Pick the row that matches your endpoint before writing client code.

Decision tree#

Is the endpoint a list (GET collection)?
├─ No  → single object (no pagination)
├─ Yes → Does OpenAPI show `cursor` instead of `page`?
│        ├─ Yes → CURSOR (timesheet_idle_times only)
│        └─ No  → Does the 200 schema describe a bare array?
│                 ├─ Yes → BARE ARRAY (screenshots, payment_settings)
│                 └─ No  → OFFSET envelope
│                          ├─ limit max 100 → standard (default 50)
│                          └─ limit max 20  → report tier (default 20)

Shape reference#

1. Offset envelope (standard)#

Used by: organization, project, payroll, leaves, and suspicious-activity list endpoints.

Response:

{
  "count": 42,
  "next": "https://api.apploye.com/v1/members/?page=2&limit=50",
  "previous": null,
  "results": [ ... ]
}

Walk pages with page until next is null. count is the total across all pages.

2. Offset envelope (report tier)#

Used by: time_activity_reports, manual_timesheet_reports, clockinouts, app_reports, url_reports.

Same envelope as standard offset, but tighter limits because each row carries aggregated or nested data:

3. Cursor envelope#

Used by: GET /v1/timesheet_idle_times/ only.

Do not send page. Use cursor from the prior response.

Response:

{
  "results": [
    {
      "user": { "user_id": "...", "email": "..." },
      "timesheets": [ { "id": "...", "idle_times": [] } ]
    }
  ],
  "pagination": {
    "limit": 10,
    "timesheets_cap": 1000,
    "users_returned": 1,
    "timesheets_returned": 42,
    "total_users": 85,
    "has_more": true,
    "next_cursor": "eyJ..."
  }
}

Walking pages:

1. Call without cursor for the first page.
2. If pagination.has_more is true, pass pagination.next_cursor as cursor on the next request.
3. Repeat until has_more is false.

Timesheet cap: at most 1,000 timesheets per response. Users are never split across pages.

Common errors:

See ADR-023 for why timesheets use cursor pagination.

4. Bare array#

Used by: GET /v1/screenshots/, GET /v1/members/{user_id}/payment_settings/.

Returns [...] with no count, next, or pagination wrapper. Result sets are bounded by required filters (user + date for screenshots).

Endpoint matrix#

Retrieve endpoints (retrieveOrganization, retrieveClient, …) return a single object — no pagination parameters.

Offset stability note#

Entity lists (members, projects, clients) may show duplicates or gaps if rows are inserted or deleted between page requests. This is accepted for admin-style paging. For high-churn data syncs, use updated_since polling on supported endpoints or cursor pagination on timesheets.

Related docs#

• Quickstart
• API Reference — OffsetPaginatedEnvelope, CursorPaginatedEnvelope