Pagination

All FHIR search endpoints return a Bundle of type searchset. Navigation through large result sets uses cursor-based pagination — not page numbers or offsets.

#Parameters

Request the first page:

curl "https://api.huli.ai/fhir/R4/Patient?_count=50" \
  -H "Authorization: Bearer $HULI_API_KEY" \
  -H "Accept: application/fhir+json"

#Response structure

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 847,
  "link": [
    {
      "relation": "self",
      "url": "https://api.huli.ai/fhir/R4/Patient?_count=50"
    },
    {
      "relation": "next",
      "url": "https://api.huli.ai/fhir/R4/Patient?_count=50&_cursor=eyJ0IjoiMjAyNi0wNi0wMVQxNDozMjowMC4wMDAtMDY6MDAiLCJpZCI6IjAxOTY1ZTJhLThjNGQtNzAwMC05MDAxLTAwMDAwMDAwMDAwMiJ9"
    }
  ],
  "entry": [...]
}

• total — the total number of matching resources at the time the first page was queried. It is advisory. For large sets it may become inaccurate as records are added or updated while you paginate. Do not use total as a loop terminator.
• link[relation=next] — present when there are more results. Absent on the last page.
• link[relation=self] — the canonical URL for the current page.

#Iterating all pages

Pass the full next URL as-is to retrieve the next batch. The cursor encodes a time+UUID position. Do not parse or construct cursor strings manually — the format may change.

NEXT_URL="https://api.huli.ai/fhir/R4/Patient?_count=50&_cursor=eyJ0IjoiMj..."

curl "$NEXT_URL" \
  -H "Authorization: Bearer $HULI_API_KEY" \
  -H "Accept: application/fhir+json"

Stop when the response has no link with relation: "next".

#Stable iteration

The cursor is time+UUID ordered. Pages are stable within a single pagination session — new records created after the first request will not appear in subsequent pages of that session, and deleted records will not cause gaps. This makes the API safe for full patient-list syncs that span multiple pages.

#Combining with filters

Search parameters combine with pagination. All parameters carry forward in the next link — you do not need to re-specify them:

curl "https://api.huli.ai/fhir/R4/Patient?name=Fernández&active=true&_count=25" \
  -H "Authorization: Bearer $HULI_API_KEY" \
  -H "Accept: application/fhir+json"

The next link for this response will include name=Fernández&active=true&_count=25 alongside the cursor.

#Empty result sets

When no resources match, the response is still a valid Bundle:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "link": [
    {
      "relation": "self",
      "url": "https://api.huli.ai/fhir/R4/Patient?name=DoesNotExist"
    }
  ],
  "entry": []
}

entry is an empty array. There is no next link.