skills/fhir-developer-skill/references/pagination.md

FHIR Pagination

All search results MUST support pagination. Return a Bundle with navigation links.

Table of Contents

• Search Response Structure
• Pagination Parameters
• Link Relations
• Implementation Example
• Additional Search Modifiers

Search Response Structure

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 150,
  "link": [
    {
      "relation": "self",
      "url": "https://fhir.example.org/Patient?name=Smith&_count=10"
    },
    {
      "relation": "next",
      "url": "https://fhir.example.org/Patient?name=Smith&_count=10&_offset=10"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir.example.org/Patient/123",
      "resource": { "resourceType": "Patient", "id": "123" },
      "search": { "mode": "match" }
    }
  ]
}

Pagination Parameters

Parameter	Description	Default
_count	Number of results per page	Server-defined (often 10-100)
_offset	Starting index (0-based)	0
_page	Alternative to offset (1-based page number)	1

Link Relations

Relation	Description
self	Current page URL
first	First page
previous	Previous page (if not on first)
next	Next page (if more results exist)
last	Last page

Implementation Example

@app.get("/Patient")
async def search_patients(
    name: str = None,
    _count: int = 10,
    _offset: int = 0
):
    # Query with limit + 1 to detect if there are more results
    results = db.query_patients(name=name, limit=_count + 1, offset=_offset)
    has_more = len(results) > _count
    results = results[:_count]  # Trim to requested count

    base_url = f"{BASE_URL}/Patient"
    params = f"name={name}&_count={_count}" if name else f"_count={_count}"

    links = [
        {"relation": "self", "url": f"{base_url}?{params}&_offset={_offset}"}
    ]

    if _offset > 0:
        prev_offset = max(0, _offset - _count)
        links.append({"relation": "previous", "url": f"{base_url}?{params}&_offset={prev_offset}"})

    if has_more:
        links.append({"relation": "next", "url": f"{base_url}?{params}&_offset={_offset + _count}"})

    return {
        "resourceType": "Bundle",
        "type": "searchset",
        "total": db.count_patients(name=name),
        "link": links,
        "entry": [
            {"fullUrl": f"{base_url}/{p['id']}", "resource": p, "search": {"mode": "match"}}
            for p in results
        ]
    }

Additional Search Modifiers

Parameter	Description	Example
_sort	Sort by field (prefix - for descending)	_sort=-date,name
_elements	Return only specified fields	_elements=name,birthDate
_summary	Return summary view	_summary=true
_include	Include referenced resources	_include=Observation:patient
_revinclude	Include resources that reference this	_revinclude=Observation:patient