Usage

The Usage APIs allow you to retrieve information about document retrieval queries and monthly active users for your organization. This data can be used for tracking, reporting, and reconciliation purposes.

Overview

HealthEx tracks document retrieval queries and categorizes them into two types:

• TEFCA queries: Queries made through the TEFCA (Trusted Exchange Framework and Common Agreement) network
• Non-TEFCA queries: Queries made through other supported networks

The summary also reports active users by Pacific calendar month. An active user is a distinct, non-test patient who either completed an IAL2 login or had a successful non-TEFCA document retrieval for the organization during that month. Patients merged into the same current patient record are counted once.

Authorization

Usage APIs require organization administrator permissions. Only users with the ORG_ADMIN permission can access these endpoints.

Endpoints

Get Usage Summary

Returns aggregate query counts for your organization within a specified date range, plus usage grouped by Pacific calendar month.

GET https://api.healthex.io/v1/usage/summary?startDate={startDate}&endDate={endDate}
Authorization: Bearer <JWT Token>

Query Parameters

Parameter	Type	Required	Description
startDate	string (ISO 8601)	Yes	Start date for the usage period
endDate	string (ISO 8601)	Yes	End date for the usage period

Example Request

curl -X GET "https://api.healthex.io/v1/usage/summary?startDate=2026-08-01T07:00:00Z&endDate=2026-10-01T06:59:59Z" \
  -H "Authorization: Bearer <JWT Token>"

Example Response

{
    "tefcaQueries": 150,
    "nonTefcaQueries": 75,
    "totalQueries": 225,
    "monthlyUsage": [
        {
            "month": "2026-08",
            "activeUsers": 92,
            "tefcaQueries": 100,
            "nonTefcaQueries": 40,
            "totalQueries": 140,
            "queriesBySource": [
                { "source": "TEFCA", "queries": 100 },
                { "source": "FASTEN", "queries": 10 },
                { "source": "PARTICLE", "queries": 8 },
                { "source": "HEALTHEX_EPIC", "queries": 7 },
                { "source": "HEALTHEX_ORACLE", "queries": 6 },
                { "source": "HEALTHEX_ECW", "queries": 5 },
                { "source": "HEALTHEX_ATHENA", "queries": 4 }
            ]
        },
        {
            "month": "2026-09",
            "activeUsers": 79,
            "tefcaQueries": 50,
            "nonTefcaQueries": 35,
            "totalQueries": 85,
            "queriesBySource": [
                { "source": "TEFCA", "queries": 50 },
                { "source": "FASTEN", "queries": 9 },
                { "source": "PARTICLE", "queries": 8 },
                { "source": "HEALTHEX_EPIC", "queries": 6 },
                { "source": "HEALTHEX_ORACLE", "queries": 5 },
                { "source": "HEALTHEX_ECW", "queries": 4 },
                { "source": "HEALTHEX_ATHENA", "queries": 3 }
            ]
        }
    ]
}

Monthly Usage

• month uses YYYY-MM and represents a calendar month in America/Los_Angeles, including daylight-saving transitions.
• monthlyUsage includes every Pacific calendar month touched by the requested range. Each row covers the complete calendar month, so an edge month can include activity outside the exact requested timestamps. The top-level totals retain their existing date-range behavior.
• activeUsers reports distinct eligible users with qualifying activity during each month.
• monthlyUsage may be incomplete before September 2026 and may not reconcile with top-level totals for earlier periods.
• queriesBySource always uses the same source categories. A source with no queries has a count of zero.

Get Usage Details

Returns paginated patient-level query details for your organization within a specified date range.

GET https://api.healthex.io/v1/usage/details?startDate={startDate}&endDate={endDate}&page={page}&pageSize={pageSize}
Authorization: Bearer <JWT Token>

Query Parameters

Parameter	Type	Required	Description
startDate	string (ISO 8601)	Yes	Start date for the usage period
endDate	string (ISO 8601)	Yes	End date for the usage period
page	number	No	Page number (default: 1)
pageSize	number	No	Results per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.healthex.io/v1/usage/details?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&page=1&pageSize=20" \
  -H "Authorization: Bearer <JWT Token>"

Example Response

{
    "total": 45,
    "page": 1,
    "pageSize": 20,
    "results": [
        {
            "patientId": "patient-uuid-1",
            "referenceIds": ["reference-id-1", "reference-id-2"],
            "tefcaQueries": 3,
            "nonTefcaQueries": 2
        },
        {
            "patientId": "patient-uuid-2",
            "referenceIds": [],
            "tefcaQueries": 1,
            "nonTefcaQueries": 0
        }
    ]
}

Date Range Limits

• The date range cannot exceed 366 days
• endDate must be after startDate

Error Responses

Status Code	Description
400	Invalid date range (exceeds 366 days or endDate before startDate)
401	Unauthorized - Invalid or missing JWT token
403	Forbidden - User does not have ORG_ADMIN permission