Overview

FHIR endpoints can return large datasets on queries for patient data. To optimize network traffic and make responses more manageable, Health Gorilla implements pagination on our FHIR endpoints.

Pagination is enforced on release version 01-01-2023 and higher . Earlier release versions support pagination but do not enforce it. Pagination is not available for Observation resources with a category of Laboratory.

Offset Pagination

Offset pagination supports the _count and _offset parameters. For endpoints that enforce pagination, the default count per page is 20 resources. The maximum number of resources per page is 100.

Parameters

Parameter	Description
_count	Specifies the number of FHIR resources returned in each response payload.
_offset	Specifies the resource that begins the next set of data.

Example Query

This example uses the MedicationStatement endpoint to pull a patient’s medication list . The example patient has a Health Gorilla ID of 2b22006136c57f8d38f0bbe4 and 175 medications in their patient chart. A query to the MedicationStatement endpoint was executed, specifying 50 resources per response payload using the _count parameter.

https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_count=50

The response payload returns the first 50 MedicationStatement resources for the specified patient. If the patient has more resources than specified in the _count parameter, a set of related URLs will be found in the link field of the response payload.

Initial Query Response Example

"link": [
       {
           "relation": "self",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_count=50"
       },
       {
           "relation": "first",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=0&_count=50"
       },
       {
           "relation": "last",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=150&_count=50"
       },
       {
           "relation": "next",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=50&_count=50"
       }
   ],

Relation	Description
Self	The original query URL that was used to retrieve the payload.
First	The query URL required to retrieve the first set of data in the paginated dataset.
Last	The query URL required to retrieve the last set of data in the paginated dataset.
Next	The query URL required to retrieve the next set of data in the paginated dataset.

GET the Next Set of Data

To retrieve the next set of data, make a query to the Next url from the previous query. This returns the next set of data in the paginated dataset.

https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=50&_count=50

Next Query Response Example

"link": [
       {
           "relation": "self",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=50&_count=50"
       },
       {
           "relation": "first",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=0&_count=50"
       },
       {
           "relation": "last",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=150&_count=50"
       },
       {
           "relation": "previous",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=0&_count=50"
       },
       {
           "relation": "next",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=100&_count=50"
       }
   ],

Relation	Description
Self	The original query URL that was used to retrieve the payload.
First	The query URL required to retrieve the first set of data in the paginated dataset.
Last	The query URL required to retrieve the last set of data in the paginated dataset.
Next	The query URL required to retrieve the next set of data in the paginated dataset.
Previous	The query URL required to retrieve the previous set of data in the paginated dataset.

Retrieving the Complete Dataset

To retrieve the complete paginated dataset, continue to query the URL in the Next field in each response payload. The last response payload does not contain a Next field. This indicates that you have retrieved all of the data from the paginated dataset.

Last Query Response Example

"link": [
       {
           "relation": "self",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=150&_count=50"
       },
       {
           "relation": "first",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=0&_count=50"
       },
       {
           "relation": "last",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=150&_count=50"
       },
       {
           "relation": "previous",
           "url": "https://sandbox.healthgorilla.com/fhir/R4/MedicationStatement?patient=2b22006136c57f8d38f0bbe4&_offset=100&_count=50"
       }
   ],

Cursor Pagination

Cursor Pagination is used when retrieving large datasets of 10,000+ resources. Currently, Health Gorilla supports cursor pagination on the Organization and Patient FHIR API endpoints. Cursor pagination supports the _paging and _count parameters. The default _count per page is 20. The maximum number of resources per page is 100.

Parameter	Description
`_paging`	Will always be set to “cursor”
`_count`	Specifies the number of FHIR resources returned in each response payload with a max of 100 per page

Example Query

https://sandbox.healthgorilla.com/fhir/R4/Patient?_paging=cursor&_count=100