Kick off the export with GET {base}/$export (system), GET {base}/Group/{id}/$export (cohort), or GET {base}/Patient/$export (all patients), adding the header Prefer: respond-async.
Receive a 202 Accepted response with a Content-Location header pointing to a polling URL; store this URL.
Poll the Content-Location URL with GET requests; a 202 means the job is still running, a 200 with a JSON body means the export is complete.
Parse the completion JSON for output[].url entries, each pointing to an ndjson file; also check error[] for partial failures.
Download each ndjson file; each line is a standalone FHIR resource JSON object—process line by line to avoid loading the whole file into memory.
If supported, send DELETE to the Content-Location URL after processing to release server-side resources.
Known gotchas
Bulk export files may be large; stream and process line-by-line rather than loading entire files into memory, and be prepared for multi-gigabyte exports in production.
Access to bulk export endpoints typically requires system-level scopes (system/*.read) via backend services (JWT client credentials) rather than user-delegated tokens.
Export files may be available for only a limited window after completion; download promptly and do not rely on the URLs remaining valid indefinitely.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp