Usage Analytics

Usage analytics is a root-key endpoint. Use it to review consumption across your organisation, for one API key, or for a selected set of API keys.The response tracks three separate usage dimensions: usage is request count, tokens is LLM token usage, and stt_duration is transcription usage in seconds.Omit key filters to get an organisation-wide view. Use api_key_id for one key or api_key_ids for a selected group of keys. Use one filtering mode per request.Totals cover the full date range. deltas gives the day-by-day breakdown. The api_key block is returned only when you request exactly one key.
POST /api/v1/usage-analytics
Retrieves usage analytics for your organisation or for selected API keys. This endpoint requires a root API key.HEADER PARAMETERS
REQUIREDX-Scrubs-Clinic-Api-Keystring
Your API key for authentication.
REQUIREDX-Scrubs-Clinic-Providerstring
Provider ID associated with your EHR application.
BODY PARAMETERS
REQUIREDstart_datestring
Start date for the analytics period in YYYY-MM-DD format.
REQUIREDend_datestring
End date for the analytics period in YYYY-MM-DD format.
OPTIONALapi_key_idstring
Optional. Returns analytics for one specific API key. If omitted, analytics are returned for the whole organisation unless api_key_ids is supplied.
OPTIONALapi_key_idsstring[]
Optional. List of API key IDs to aggregate together in one response.
Error Codes7 cases
Request validation
400Request body is invalid.start_date and end_date are required in YYYY-MM-DD format. start_date must be before or equal to end_date.
Common API key authentication errors
400Provider ID is invalid.The X-Scrubs-Clinic-Provider header does not map to a known organisation.
401API key authentication failed.The API key or provider header is missing, or the supplied API key is invalid for the provider.
500Unexpected server failure.Repository, database, or service errors while reading or mutating API key data.
Root API key requirement
403Root API key is required.The authenticated key is valid but does not have root-level permission for this operation.
Target API key validation
403Target API key is outside the organisation.A requested api_key_id belongs to a different organisation than the authenticated root key.
404Target API key was not found.The requested api_key_id does not exist or is unavailable.
Domain
BASE URL
1https://usescrubs.com
Sample Request
CURL
Node.JS
Python
Go
CURL
1curl --location --request POST 'https://usescrubs.com/api/v1/usage-analytics' \
2--header 'X-Scrubs-Clinic-Api-Key: your_root_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
4--header 'Content-Type: application/json' \
5--data '{
6  "start_date": "2024-01-01",
7  "end_date": "2024-01-31"
8}'
9
10# To query one specific API key:
11curl --location --request POST 'https://usescrubs.com/api/v1/usage-analytics' \
12--header 'X-Scrubs-Clinic-Api-Key: your_root_api_key_here' \
13--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
14--header 'Content-Type: application/json' \
15--data '{
16  "api_key_id": "key_uuid_here",
17  "start_date": "2024-01-01",
18  "end_date": "2024-01-31"
19}'
20
21# To query a selected group of API keys:
22curl --location --request POST 'https://usescrubs.com/api/v1/usage-analytics' \
23--header 'X-Scrubs-Clinic-Api-Key: your_root_api_key_here' \
24--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
25--header 'Content-Type: application/json' \
26--data '{
27  "api_key_ids": ["key_uuid_here", "key_uuid_here_2"],
28  "start_date": "2024-01-01",
29  "end_date": "2024-01-31"
30}'
Sample Response
JSON
1{
2  "api_key": {
3    "id": "key_123456789",
4    "friendly_name": "Production EHR Integration",
5    "created": "2024-01-15T10:30:00Z",
6    "usage_limit": 1000,
7    "monthly_stt_secs_limit": 7200,
8    "monthly_token_limit": 5000000,
9    "root": false
10  },
11  "total": {
12    "stt_duration": 120,
13    "tokens": 5000000,
14    "usage": 150
15  },
16  "deltas": {
17    "2024-01-15": {
18      "tokens": 1000000,
19      "usage": 25,
20      "stt_duration": 30
21    },
22    "2024-01-16": {
23      "tokens": 800000,
24      "usage": 20,
25      "stt_duration": 25
26    }
27  }
28}
Contact us: support@usescrubs.com