Pagination

The Health Gorilla FHIR API supports pagination for search operations and $everything responses. This ensures efficient handling of large result sets and prevents timeouts or performance degradation.

Paginated responses return a FHIR Bundle with one or more navigation links.

Default Behavior

By default, most search responses return the first page of results only. If more data is available, the response includes a link.relation="next" entry with a URL to fetch the next page.

For example, the GET /Observation?patient=123456 request returns this response:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 125,
  "link": [
    {
      "relation": "next",
      "url": "https://api.healthgorilla.com/fhir/R4/Observation?patient=123456&_count=50&_offset=50"
    }
  ],
  "entry": [
    { "resource": { ... } },
    { "resource": { ... } }
  ]
}

Supported Pagination Parameters

_count is part of the FHIR specification. _offset and _paging are Health Gorilla parameters that control how the next link is built, so don't expect them on other FHIR servers. Whichever you use, follow the next link exactly as the server returns it rather than building your own.

Cursor Paging

With cursor paging, your position in the result set is recorded in the next link, so a record can't be missed or repeated when the underlying data changes between requests. Offset paging gives no such guarantee.

Cursor paging is available on Patient and Organization searches. Request it by adding _paging=cursor, then follow the next link until no next link is returned. Every other resource type supports offset paging only.

Three limits apply on Patient and Organization searches:

• A _count above 100 is rejected with a 400, whether or not you use cursor paging. The default when you supply no _count is 20.
• A cursored request that also carries _offset greater than zero is rejected with a 400 reading "_offset parameter not supported with cursored request".
• An offset request where _offset plus _count reaches 10,000 is rejected with a 400 reading "Maximum search depth exceeded". A cursored request has no depth limit.

By default a cursor stays valid for five minutes, and each request restarts the clock. So, request the next page within five minutes of the one before it. Contact Health Gorilla to confirm the value for your environment. A cursor that has expired can't be resumed; you'll need to start the search again from the beginning.

Usage

• Use _count to control page size: GET /Encounter?patient=123456&_count=50
• Start cursor paging on a Patient or Organization search: GET /Patient?family=Smith&_count=50&_paging=cursor
• Continue any subsequent page by following Bundle.link.next as returned, without editing the link.
• Offset paging returns a window into a result set that is re-evaluated on every request, so records can shift between pages if the data changes while paging.

Best Practices

• Always follow Bundle.link.next as returned
• On a Patient or Organization search, prefer cursor paging whenever the data could change while paging, and keep _count at 100 or below in either mode
• Set _count to manage response size and performance
• Avoid excessively large page sizes, for example _count=1000
• Reserve _offset for short, one-off lookups rather than long paging sequences

Applies To

• All FHIR search requests, such as: GET /ResourceType?...
• $everything responses
• Other operations that return FHIR Bundles