Skip to main content

Getting Data Retrieval Status

This endpoint provides comprehensive information about the data retrieval progress, including retrieval status for each healthcare location and vectorization status.

How Data Retrieval Status Works​

When a patient consents to share their health data, HealthEx initiates a data retrieval process that may fetch records from multiple healthcare locations. This API allows you to monitor the progress of that retrieval and see the vectorization status (which indicates whether the data is ready for AI-powered queries).

Authentication​

This endpoint requires a valid Patient Token (either full access or read-only).

See the Authentication guide for more information on obtaining tokens.

Making the API Call​

To get the data retrieval status:

GET https://api.healthex.io/v1/patients/data-retrieval/status
Accept: application/json
Authorization: Bearer <patient JWT token>

This API requires you to pass a patient JWT token to authenticate. See the Authentication guide for more info.

Response Format​

If the request is successful, we will respond with a 200 status code. The response body will look something like this:

{
    "patientId": "17d4513f-73e8-4b2a-9c1d-5e6f7a8b9c0d",
    "retrievalId": "batch-abc123-def456",
    "dataRetrievalStatus": "IN_PROGRESS",
    "vectorizationStatus": "IN_PROGRESS",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T11:45:00.000Z",
    "locations": [
        {
            "locationId": "loc-hospital-123",
            "locationName": "General Hospital",
            "locationLogoUrl": "https://example.com/logo.png",
            "locationSource": "TEFCA_DOCUMENT",
            "dataRetrievalStatus": "COMPLETE",
            "updatedAt": "2024-01-15T11:30:00.000Z",
            "documentCount": 5
        },
        {
            "locationId": "loc-clinic-456",
            "locationName": "Downtown Clinic",
            "locationLogoUrl": null,
            "locationSource": "USER_SELECTED",
            "dataRetrievalStatus": "IN_PROGRESS",
            "updatedAt": "2024-01-15T11:45:00.000Z",
            "documentCount": 0
        }
    ]
}

Response Fields​

  • patientId: The patient's unique identifier
  • retrievalId: Unique identifier for this retrieval batch
  • dataRetrievalStatus: Overall status of the data retrieval (see values below)
  • vectorizationStatus: Status of data vectorization for AI queries (see values below)
  • createdAt: ISO 8601 timestamp of when the retrieval was initiated
  • updatedAt: ISO 8601 timestamp of the most recent update across all locations and vectorization (null if never updated)
  • locations: Array of location-specific retrieval statuses

Location Fields​

Each location in the locations array contains:

  • locationId: Unique identifier for the healthcare location
  • locationName: Human-readable name of the location (may be null)
  • locationLogoUrl: URL to the location's logo image (may be null)
  • locationSource: How this location was discovered (see values below)
  • dataRetrievalStatus: Retrieval status for this specific location
  • updatedAt: ISO 8601 timestamp of the last update for this location (may be null)
  • documentCount: Number of documents retrieved from this location

Overall Data Retrieval Status Values​

The overall dataRetrievalStatus field indicates the status of the current retrieval:

  • IN_PROGRESS: The retrieval is still active and not yet finalized
  • COMPLETE: The retrieval has been finalized, meaning all processing is complete

Location Data Retrieval Status Values​

Each location's dataRetrievalStatus field indicates the retrieval progress for that specific healthcare location:

  • NOT_STARTED: Retrieval has not begun for this location
  • IN_PROGRESS: Data is currently being retrieved from this location
  • COMPLETE: Data retrieval completed successfully for this location
  • PARTIAL_COMPLETE: Some documents were retrieved, but the process encountered issues
  • SKIPPED: This location was skipped (e.g., patient opted out)
  • ERROR: An error occurred during retrieval from this location

Location Source Values​

The locationSource field indicates how the healthcare location was discovered:

  • TEFCA_DOCUMENT: Discovered through a TEFCA document query
  • TEFCA_ENDPOINT: Discovered through a TEFCA endpoint query
  • USER_SELECTED: Manually selected by the patient

Vectorization Status Values​

The vectorizationStatus field indicates whether the retrieved data has been processed for AI-powered queries:

  • IN_PROGRESS: Data is being prepared for AI queries (includes queued, waiting, and actively processing states)
  • COMPLETE: Vectorization completed successfully - data is ready for AI-powered queries
  • FAILED: Vectorization encountered an error

Error Responses​

We may return errors in the following scenarios:

No Retrieval Found​

HTTP 404 - No data retrieval request was found for the patient. This may mean the patient has not initiated a data retrieval process yet, or the retrieval was aborted before document selection was completed.

Unauthorized​

HTTP 401 - The token is missing, invalid, or expired.

Forbidden​

HTTP 403 - The token does not have permission to access this endpoint. This typically happens when the token is not a patient token (PATIENT or PATIENT_READ_ONLY type).

Usage Notes​

  • This endpoint only returns the most recent data retrieval batch for the patient where document selection was completed
  • The updatedAt timestamp reflects the latest update across all locations and vectorization processing
  • When vectorizationStatus is COMPLETE, the patient's data is ready for AI-powered queries via the MCP server

See Also​