Skip to content

Pagination

The Nymbl API uses OData-style cursor pagination via $top and $skip. All collection endpoints return a maximum of 100 records per page by default.

Parameters

Parameter Type Description
$top Integer Number of records to return (max 100)
$skip Integer Number of records to skip
$count Boolean Include total count of matching records

Basic Example

Retrieve the first 25 patients:

GET /Patients?$top=25

Retrieve the next 25 (page 2):

GET /Patients?$top=25&$skip=25

Page 3:

GET /Patients?$top=25&$skip=50

Including a Total Count

Add $count=true to get the total number of matching records alongside the page results:

curl -X GET "https://api.nymbldev.com/Patients?\$top=25&\$skip=0&\$count=true" \
  -H "Authorization: Bearer eyJraWQiOiJ..." \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "@odata.context": "https://api.nymbldev.com/$metadata#Patients",
  "@odata.count": 1500,
  "value": [
    { "id": "1", "first_name": "Jane", "last_name": "Doe" },
    ...
  ]
}

Use @odata.count to determine total pages: ceil(1500 / 25) = 60 pages.

Paginating with Filters

Pagination works in combination with $filter. The skip/top is applied after filtering:

GET /Patients?$filter=active eq true&$top=50&$skip=100

Python Example — Fetch All Pages

import requests

token = "eyJraWQiOiJ..."
api_key = "YOUR_API_KEY"
base_url = "https://api.nymbldev.com/Patients"
headers = {
    "Authorization": f"Bearer {token}",
    "x-api-key": api_key
}

page_size = 100
skip = 0
all_patients = []

while True:
    response = requests.get(
        base_url,
        headers=headers,
        params={"$top": page_size, "$skip": skip, "$count": "true"}
    )
    response.raise_for_status()
    data = response.json()

    all_patients.extend(data["value"])
    total = data.get("@odata.count", 0)

    skip += page_size
    if skip >= total:
        break

print(f"Fetched {len(all_patients)} patients")

Consistent Ordering

Always include $orderby when paginating to ensure stable, consistent page results:

GET /Patients?$top=25&$skip=25&$orderby=id asc

Without a consistent sort order, records may shift between pages if data changes during pagination.

Best Practices

Tip

  • Use $count=true on the first page to calculate total pages upfront
  • Always specify $orderby when paginating to avoid duplicate or skipped records
  • For bulk data exports, use the maximum page size of 100 to minimize the number of requests
  • Combine with $filter to paginate only over the records you need