Some long-running operations in the Health Gorilla API are executed asynchronously to avoid timeouts or performance bottlenecks. This applies to operations like $everything, $p360-retrieve, and certain large queries.

Asynchronous processing is used primarily in the FHIR STU3 API, since most standard queries in FHIR R4 are synchronous by default. Further, this topic only applies to operations like $everything and $p360-retrieve, and other large document or record queries.

When the server determines a request should run asynchronously, it returns a 202 Accepted response with a polling URL in the Location or Content-Location header.

Triggering Async Mode

Clients can explicitly request asynchronous processing using the Prefer header. For example, Prefer: respond-async.

This instructs the server to accept the request and return immediately, while processing the job in the background.

Handling Async Responses

Once a request is accepted for asynchronous processing, clients can track its progress using webhook notifications or polling.

Recommended: Webhooks

Webhooks enable event-driven notifications, allowing clients to receive updates when a job completes without polling. This push-based model is more efficient than polling and reduces the number of API calls.

To receive a webhook notification when an async job finishes, subscribe using a FHIR Subscription:

{
  "resourceType": "Subscription",
  "status": "active",
  "criteria": "OperationOutcome?async=true",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://example.com/webhook",
    "payload": "application/fhir+json"
  }
}

Fallback: Polling

Polling is an alternative for environments that cannot receive inbound HTTP requests or require simpler integration. In these cases, clients should use exponential backoff and be prepared to handle various response states.

Request

GET /fhir/RequestResult/3ce13b5ecb4d6633826caca0

Responses

In Progress

HTTP/1.1 202 Accepted  
X-Progress: in progress

Success

HTTP/1.1 200 OK
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "entry": [ ... ]
}

Expired or Not Found

HTTP/1.1 454 Expired or Not Found

Best Practices

Use Prefer: respond-async for potentially large or long-running requests (STU3 only)
Implement webhook notifications for event-driven completion signals
Use polling only as a fallback when webhooks are not feasible
Apply exponential backoff when polling to reduce load
Handle all relevant status codes gracefully (202, 200, 454)