Export Poll Status Operation

Overview

The Export Poll Status Operation checks the status of a bulk data export job and retrieves the file manifest when the export is complete. This operation supports both status checking and export cancellation.

Operation: GET /$export-poll-status

Key Use Cases:

• Monitor export job progress
• Retrieve file download URLs when export completes
• Cancel running export jobs
• Handle export errors and troubleshooting

Important: The status URL is provided in the Content-Location header when an export is initiated. Always use the exact URL returned by the export operation.

Parameters

Name	Type	Required	Description
_id	string	Yes	Export job ID from Content-Location header

Operations

Check Export Status

Retrieves the current status of an export job.

Endpoint: GET /$export-poll-status?_id={job-id}

Examples

Production

Check Export Status

curl -X GET "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/\$export-poll-status?_id=abc123" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json"

Preview

Check Export Status

curl -X GET "https://fhirtest.netsmartcloud.com/uscore/v1/bulk-data/\$export-poll-status?_id=abc123" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json"

Response Examples

Export In Progress:

Export Still Processing

HTTP/2 202 Accepted
X-Progress: 50% complete
X-RetryAfter: 120

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "information",
    "code": "informational",
    "diagnostics": "Export job is still processing. Check back later."
  }]
}

Export Complete:

Export Completed Successfully

HTTP/2 200 OK
Content-Type: application/json

{
  "transactionTime": "2024-01-15T10:30:00Z",
  "request": "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Group/example-group/$export",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "Patient",
      "url": "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/patient-file-123/$binary-access-read",
      "count": 150
    },
    {
      "type": "Observation",
      "url": "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/observation-file-456/$binary-access-read",
      "count": 2847
    }
  ],
  "error": [
    {
      "type": "OperationOutcome",
      "url": "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/Binary/error-file-789/$binary-access-read",
      "count": 5
    }
  ]
}

Cancel Export

Cancels a running export job.

Endpoint: DELETE /$export-poll-status?_id={job-id}

Examples

Production

Cancel Export Job

curl -X DELETE "https://fhir.netsmartcloud.com/uscore/v1/bulk-data/\$export-poll-status?_id=abc123" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json"

Preview

Cancel Export Job

curl -X DELETE "https://fhirtest.netsmartcloud.com/uscore/v1/bulk-data/\$export-poll-status?_id=abc123" \
    -H "Authorization: Bearer {access_token}" \
    -H "Accept: application/fhir+json"

Response Example

Export Cancelled

HTTP/2 202 Accepted

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "information",
    "code": "informational",
    "diagnostics": "Export job has been cancelled successfully"
  }]
}

Integration Patterns

Polling Strategy

# Recommended polling approach
while true; do
  response=$(curl -s -D headers.txt -w "%{http_code}" -X GET "$status_url" \
    -H "Authorization: Bearer $token")
  
  http_code=${response: -3}
  
  if [ "$http_code" = "200" ]; then
    echo "Export complete!"
    # Parse file manifest and download files
    break
  elif [ "$http_code" = "202" ]; then
    echo "Export in progress, waiting..."
    # Use X-RetryAfter header value, default to 30 seconds if not present
    retry_after=$(grep -i "x-retryafter:" headers.txt | cut -d' ' -f2 | tr -d '\r')
    sleep ${retry_after:-30}
  else
    echo "Export failed with status: $http_code"
    break
  fi
done

File Manifest Processing

# Extract file URLs from completed export
jq -r '.output[].url' export_manifest.json | while read url; do
  filename=$(basename "$url" | cut -d'/' -f1)
  curl -X GET "$url" \
    -H "Authorization: Bearer $token" \
    -o "$filename.ndjson"
done

Export Status States

HTTP Status	Description	Action
202 Accepted	Export in progress	Continue polling
200 OK	Export complete	Download files from manifest
404 Not Found	Invalid job ID or export expired	Verify job ID and URL, re-initiate export if expired
500 Server Error	Export failed	Check error details, retry if appropriate

File Manifest Structure

Output Files

• type: FHIR resource type contained in file
• url: Download URL for Binary/$binary-access-read
• count: Number of resources in file (optional)

Error Files

• type: Always "OperationOutcome"
• url: Download URL for error details
• count: Number of error entries (optional)

Error Handling

For comprehensive error scenarios and troubleshooting guidance, see Common Errors.

Relationships to Other Operations

• Group Export: Provides the status URL in Content-Location header
• Binary Access Read: Download files using URLs from export manifest
• CapabilityStatement: Documents supported export status operations