FHIR asynchronous bulk export status tracking begins with the Content-Location header returned by a successful kick-off request. The Bulk Data Access IG states that after a bulk data request has been started, the client may poll the status URL provided in that header as described in the FHIR Asynchronous Request Pattern [1]. The kick-off request itself should include a Prefer header with respond-async, and the server may return an error or process the request as if that value was supplied when it is omitted [1]. Status responses are not uniform across implementations. Some vendors return an empty 202 Accepted body while a job runs, while others expose progress headers or a JSON status object. The practical work is distinguishing the specification's shared polling model from documented vendor boundaries around job IDs, progress indicators, and completion manifests.
The Shared Polling Pattern and Its Headers
The FHIR Bulk Data Access IG builds on the FHIR Asynchronous Request Pattern and may extend it in places [1]. A client initiates an export with a GET or POST request and receives a status URL in the Content-Location header. The client then polls that URL until the job completes. The specification recommends that clients follow an exponential backoff approach when polling for status [1]. This is a client-side behavior, not a server guarantee, and it is intended to reduce load on the export service.
Servers can shape polling behavior through response headers. The IG states that a server should supply a Retry-After header with a delay time in seconds or an http-date [1]. If a client polls too frequently, the server should respond with a 429 Too Many Requests status code in addition to a Retry-After header, and optionally a FHIR OperationOutcome resource with further explanation [2]. When a client includes Prefer: separate-export-status in the kick-off request and the server supports it, the HTTP status code in the status response reflects the status request itself rather than the export job. In that case, when the status request returns 200 OK, the response must also include an X-Export-Status header with an HTTP status code that reflects the status of the export job [2]. Without that preference, the status HTTP code itself reflects the export job and no X-Export-Status header is required. These headers create a shared vocabulary, but the body of the status response remains implementation-specific.
Vendor-Specific Status Bodies and Job Endpoints
CMS DPC documents a status flow where the kick-off returns 202 Accepted with an empty body and a Content-Location header pointing to a Jobs endpoint [7]. While the job is still running, the same URL returns 202 Accepted with no body. When the job completes, it returns 200 OK with a JSON body listing output files, counts, checksums, and file lengths [7]. DPC also warns that sending Accept: application/fhir+json to the Jobs endpoint returns 406 Not Acceptable; clients should omit the Accept header or use application/json [7]. This is a concrete boundary that differs from the FHIR OperationOutcome response format described in the specification.
WSO2's healthcare connector exposes a different status model. A successful kick-off returns HTTP 202 Accepted, and the FHIRResponse includes a JSON resource with exportId, pollingUrl, status, and bulkExportResponse fields [5]. The connector can poll by exportId or by the Content-Location URL [5]. Status responses distinguish 202 as still in progress, with progress available in the serverResponseHeaders X-Progress field [5]. This connector-level abstraction is not part of the FHIR specification; it is a documented WSO2 implementation detail that wraps the underlying server's polling behavior.
Polling Checklist for a New Export Target
Before integrating a new FHIR bulk export target, capture the kick-off response's Content-Location header and store it as the canonical status URL. Do not reconstruct the URL from a job ID unless the vendor documents that pattern. Check whether the vendor requires a specific Accept header on the status request; DPC requires omitting application/fhir+json [7], while the FHIR specification describes application/fhir+json for the kick-off OperationOutcome [1]. Record the status response body shape for 202 and 200 responses, including any X-Progress header or, when separate-export-status was requested and supported, X-Export-Status header [2][5]. Finally, confirm the token and scope requirements for polling, since Elation Health requires the same client ID as the kick-off [8].
Progress Indicators and Completion Boundaries
The FHIR specification does not define a standard progress percentage for bulk export jobs. WSO2's documentation references an X-Progress header in its status responses, but this is a connector-specific field [5]. Azure's FHIR service documentation does not describe an X-Progress header; instead, it focuses on job state and troubleshooting. Azure notes that in some situations a job can become stuck in a bad state while the FHIR service is attempting to export data [3]. The default time for an export operation to idle in a bad state is 10 minutes before the service stops the operation and moves to a new job [3]. This is a vendor-specific recovery boundary, not a specification requirement.
Completion manifests also vary in structure. DPC's completion response includes a transactionTime, request URL, requiresAccessToken flag, and an output array with type, url, count, and extension fields for checksum and file length [7]. The error array lists URLs to NDJSON files containing per-resource OperationOutcome failures [7]. Elation Health documents that exported files are hosted in a protected AWS S3 compatible bucket, and the URLs returned in the job completion response manifest are AWS S3 self-signed URLs valid for 7 days after manifest retrieval [8]. These retrieval windows and integrity fields are implementation choices that clients must handle separately.
Authorization and Scope Boundaries During Polling
Status polling is not always a public operation. Elation Health states that when polling for job status, or canceling a job, the FHIR client must have a valid auth token with the same client ID as the one used to initiate the export job [8]. This ties the status request to the original kick-off identity. Elation also documents two additional scopes, system/Export.write and system/Export.read, that permit triggering bulk exports and accessing them upon completion [8]. These scopes are separate from the resource-level read scopes that determine which data appears in the export.
athenahealth ties authorization to resource scopes and practice context. Its FHIR Bulk Export supports system-level read scopes for resources such as Patient, Observation, and Encounter, and it also supports CRUDS scopes in conformance with SMART App Launch v2.0.0 [4]. The GroupID used in the kick-off request is the Practice in the format a-1.C-{Practice} [4]. This means status tracking for an athenahealth job is inseparable from the practice context and the scopes granted to the client application. A status request that lacks the correct token or scope will not return the job state.
A Suggested Validation Scenario for Status Tracking
A useful hypothetical validation scenario would test three distinct status behaviors without assuming any vendor implements all of them. First, submit a kick-off request with Prefer: respond-async and capture the Content-Location header. Poll that URL with an Accept header omitted or set to application/json, depending on the vendor's documented requirement. Record whether the response is 202 with an empty body, 202 with an X-Progress header, or 200 with a completion manifest. Second, deliberately poll faster than the server's documented interval and observe whether a 429 Too Many Requests response appears with a Retry-After header [2]. Third, attempt to poll with a token from a different client ID and confirm whether the server rejects the request, as Elation Health documents [8].
This scenario is a suggestion for internal validation, not a claim about any tested behavior. It would help a team distinguish specification-level polling from vendor-specific job endpoints. For example, DPC's Jobs endpoint returns 406 Not Acceptable when Accept: application/fhir+json is sent [7], while the FHIR specification describes an OperationOutcome response format for the kick-off request [1]. A validation run that treats these as the same endpoint would produce misleading results. The value of the scenario is that it forces the team to document which status fields, headers, and error codes each target server actually returns.
Sources & references
- Export - Bulk Data Access IG v3.0.0 · hl7.org
- Export - Bulk Data Access IG v3.0.0 - HL7.org · www.hl7.org
- Export your FHIR data by invoking the $export command on the FHIR service | Microsoft Learn · learn.microsoft.com
- FHIR Bulk Export Workflow | API Solutions · docs.athenahealth.com
- Bulk Data Export | Healthcare Solution Documentation · healthcare.docs.wso2.com
- FHIR R4 APIs with Bulk Data Access - Bulk Export REST Endpoints · docs.oracle.com
- Export CMS Claims Data | DPC · dpc.cms.gov
- Bulk Data Export · help.elationhealth.com