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

Supported Pagination Parameters

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