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&_cursor=abc123"
    }
  ],
  "entry": [
    { "resource": { ... } },
    { "resource": { ... } }
  ]
}

Supported Pagination Parameters

Parameter	Description
`_count`	Number of resources to return per page (default varies by resource type)
`_offset`	Optional numeric index for paginating with offset-based logic
`_cursor`	Opaque server-generated pointer for retrieving the next page of results

In most cases, _cursor is returned by the server and should be used as-is. It cannot be manually constructed or modified.

Usage

Use _count to control page size: GET /Encounter?patient=123456&_count=50
Use _cursor from the Bundle.link.next to retrieve the next page: GET /Encounter?patient=123456&_cursor=abc123
Avoid using _offset for large datasets, as it may lead to performance issues or inconsistent pagination if data changes between requests.

Best Practices

Use _cursor from the response Bundle.link.next when available
Set _count to manage response size and performance
Avoid excessively large page sizes (e.g., _count=1000)
Do not rely on _offset for long-lived pagination sequences
Always handle the case where no link:next is present — this indicates the final page

Applies To

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