Pagination

List endpoints that can return many records are paginated with limit and offset query parameters.

Parameters

Parameter	Type	Default	Description
`limit`	integer	Varies by endpoint	Number of records to return (minimum `1`)
`offset`	integer	`0`	Number of records to skip before this page starts

The default and maximum limit differ per endpoint:

Operation	Path	Default `limit`	Maximum `limit`
`listTasks`	`GET /tasks`	20	100
`listReservations`	`GET /reservations`	20	100
`listDevices`	`GET /devices`	20	100
`listCodes`	`GET /lock-codes`	20	100
`listTemplates`	`GET /task-templates`	20	100
`listDepartments`	`GET /departments`	50	100
`listTeamMembers`	`GET /members`	50	100
`listProperties`	`GET /properties`	50	500
`listUpsells`	`GET /upsells`	50	200
`listClockedShifts`	`GET /clocked-shifts`	50	200
`listShifts`	`GET /shifts`	50	1000
`listTags`	`GET /tags`	100	500
`listPropertyGroups`	`GET /property-groups`	200	200

A limit outside the allowed range is rejected with 400 validation_error. It is not clamped. Other list operations (for example listPortals or listInstructions) return every matching record in one response and have no meta.pagination. search (1–50, default 20) and searchCoverIcons (1–100, default 25) take a limit cap but no offset.

Response Shape

Paginated responses include a meta.pagination object alongside the data array:

{
  "data": [
    { "id": "7d0e…", "nameText": "Deep clean unit 4B", "status": "not_started" },
    { "id": "c41a…", "nameText": "Inspect pool area", "status": "in_progress" }
  ],
  "meta": {
    "requestId": "3f1c9a52-…",
    "pagination": {
      "total": 142,
      "limit": 20,
      "offset": 0
    }
  }
}

Field	Description
`total`	Total number of records matching the query (before pagination)
`limit`	The `limit` that was applied
`offset`	The `offset` that was applied

Iterating All Pages

To retrieve all records, advance offset by limit until offset >= total:

#!/bin/bash
LIMIT=100
OFFSET=0
REGION=us

while true; do
  status=$(curl -s -o page.json -D headers.txt -w '%{http_code}' \
    "https://api-${REGION}.suiteop.com/api/v1/tasks?limit=${LIMIT}&offset=${OFFSET}" \
    -H "Authorization: Bearer sk_live_your_key_here")

  if [ "$status" = 429 ]; then
    wait=$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')
    sleep "${wait:-1}"
    continue
  elif [ "$status" != 200 ]; then
    cat page.json >&2
    exit 1
  fi
  response=$(cat page.json)

  # process $response here

  total=$(echo "$response" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['meta']['pagination']['total'])")
  OFFSET=$((OFFSET + LIMIT))

  if [ "$OFFSET" -ge "$total" ]; then
    break
  fi
done

Example: Second Page

curl "https://api-us.suiteop.com/api/v1/tasks?limit=20&offset=20" \
  -H "Authorization: Bearer sk_live_your_key_here"

Returns records 21–40.

Query Parameters in General

Numbers and booleans are read from their text form. Booleans accept true, 1 or yes and false, 0 or no.
To send an array filter, repeat the key: ?statuses=not_started&statuses=in_progress. A single value is treated as a one-element array. A comma-separated list is not split.
Query parameters an operation doesn’t declare are ignored.

Notes

total reflects the count at query time. If records are created or deleted between pages, you may see gaps or duplicates. Where an endpoint offers a date-window filter, narrowing the window reduces this.
Requesting an offset beyond total returns an empty data array with total unchanged. It is not an error.