Understanding Pagination in Epic FHIR APIs: A Developer’s Guide

Why Pagination is Needed in Epic

If an API tried to return every record in a single response, things would quickly start to break down. The response size would become very large, the request would take longer to complete, and applications consuming the API might struggle with memory usage. In extreme cases, the request could even fail or timeout.

To avoid this situation, Epic uses pagination. Instead of sending everything at once, the API divides the data into smaller chunks. Each response contains only a portion of the total dataset.

For developers integrating with Epic systems, understanding this behavior is important. Without handling pagination correctly, applications may only read the first portion of the data and miss the rest. This article explains how Epic pagination works, how it appears in FHIR responses, and how developers can handle it correctly in their applications.

What Pagination Means

Pagination is actually a straightforward concept.

Rather than returning thousands of records in one response, the server returns a limited number of records at a time. The remaining data can be accessed through additional requests.

A simple way to think about it is like reading a long document. You don’t try to read every page at once—you move through it page by page.

APIs follow the same idea.

For example:

Each response includes:

• a subset of the overall data
  
• information about how to request the next page
  

The client application keeps requesting the next page until all results have been retrieved.

Why Pagination Matters in Epic Systems

Healthcare platforms store an enormous amount of data. A single hospital environment may contain:

• hundreds of thousands of patient records
  
• millions of clinical observations
  
• long histories of encounters
  
• continuously updated information from multiple departments
  

Attempting to retrieve all of that data in a single API call would cause several problems. The response payload would become extremely large, network transfers would slow down, and applications processing the response could run into memory limitations.

Pagination solves this by limiting how much data is returned per request. Smaller responses are easier for both the server and the client application to handle. As a result, integrations remain more stable and predictable.

How Epic Handles Pagination

Epic APIs follow the FHIR standard, so most responses are returned as a Bundle resource.

Inside this bundle you will usually find:

• the actual resources returned by the query
  
• metadata about the request
  
• links that allow navigation between pages
  

A simplified example of a response might look like this:

{
"resourceType": "Bundle",
"type": "searchset",
"total": 120,
"link": [
  {
    "relation": "self",
    "url": "https://api.epic.com/fhir/Patient?_count=20"
  },
  {
    "relation": "next",
    "url": "https://api.epic.com/fhir/Patient?_count=20&_getpages=abc123"
  }
],
"entry": [
  {
    "resource": {
      "resourceType": "Patient",
      "id": "123"
    }
  }
]
}

One of the most important parts of this response is the link section.

These links help the client move through the dataset.

Common relations include:

• self – represents the current request
  
• next – points to the next page of results
  

Instead of trying to generate pagination URLs manually, developers should always use the next link returned by the API.

Retrieving All Pages from Epic

When an application needs to retrieve a large dataset from Epic, the process typically follows a simple loop.

1. Send the initial request to the API
   
2. Receive the response bundle
   
3. Process the resources inside bundle.entry
   
4. Check whether a next link is present
   
5. If a next link exists, send another request using that URL
   
6. Continue the process until no next link is returned
   

Once the next link disappears, it means the final page has been reached and the full dataset has been retrieved.

Example: Handling Epic Pagination in JavaScript

The following example shows a simple approach using Node.js to follow pagination links automatically.

const axios = require("axios");
async function fetchAllPatients(url, token) {
 let nextUrl = url;
 const patients = [];
 while (nextUrl) {
   const response = await axios.get(nextUrl, {
     headers: {
       Authorization: `Bearer ${token}`
     }
   });
   const bundle = response.data;
   if (bundle.entry) {
     bundle.entry.forEach(item => {
       patients.push(item.resource);
     });
   }
   const nextLink = bundle.link?.find(l => l.relation === "next");
   nextUrl = nextLink ? nextLink.url : null;
 }
 return patients;
}

This approach allows the application to:

• retrieve each page of results sequentially
  
• process the data from every response
  
• stop automatically when no additional pages are available
  

Common Query Parameters Used with Pagination

Epic APIs support several parameters that influence pagination behavior.

_count

This parameter controls how many records are returned per page.

Example:

/Patient?_count=20

In this case, the API will return 20 resources per response.

_since

This parameter is useful when retrieving only recently updated data.

Example:

/Observation?_since=2025-01-01T00:00:00Z

It is commonly used when running scheduled jobs that synchronize new or updated records.

_sort

Sorting can also be applied when querying resources.

Example:

/Encounter?_sort=date

Sorting helps keep results consistent across pages.