Scrubs Docs | Scrubs

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

400

Request 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

400	Provider ID is invalid.	The X-Scrubs-Clinic-Provider header does not map to a known organisation.
401	API key authentication failed.	The API key or provider header is missing, or the supplied API key is invalid for the provider.
500	Unexpected server failure.	Repository, database, or service errors while reading or mutating API key data.

Root API key requirement

403

Root API key is required.

The authenticated key is valid but does not have root-level permission for this operation.

Target API key validation

403	Target API key is outside the organisation.	A requested api_key_id belongs to a different organisation than the authenticated root key.
404	Target 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

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}

Usage Analytics