Usage and audit
Meter token and storage consumption and read the organisation's audit trail.
These routes give administrators visibility into what the organisation consumes and who did
what. Both require a key with the admin scope; see API keys for
how scopes are assigned.
Nucleus bills per million tokens plus storage, so Get usage is how you forecast spend before a bill arrives and reconcile it afterwards. Read the audit log complements it with an organisation-level event trail for security and compliance reviews.
Get usage
/v1/usagescope: adminReturns aggregated consumption for a date range. Each bucket carries train_tokens,
infer_tokens and storage_gb_hours, the three quantities your bill is computed from.
In addition to these three metered quantities, dedicated hosting is billed separately by the GPU-hour.
Group by day to plot a trend, by project to attribute spend to teams, or by model to
see which base models drive cost.
Query parameters
fromstringStart of the range, as YYYY-MM-DD.
tostringEnd of the range, as YYYY-MM-DD.
group_bystringHow to bucket the results: day, project or model.
curl "https://api.nucleus-ai.io/v1/usage?from=2026-07-01&to=2026-07-27&group_by=project" \
-H "Authorization: Bearer $NUCLEUS_API_KEY"{
"from": "2026-07-01",
"to": "2026-07-27",
"buckets": [
{
"project_id": "proj_acme",
"train_tokens": 84201170,
"infer_tokens": 2910442,
"storage_gb_hours": 1840
}
]
}Read the audit log
/v1/audit-logscope: adminReturns the organisation's event trail for a single UTC day. Each entry records when
something happened (timestamp), what it was (event), the API key that did it (actor)
and, where relevant, the checkpoint path it touched.
The log is read one day per call: pass day in UTC and walk consecutive days to cover a
longer window.
Query parameters
event_typestringWhich events to return: all or checkpoints.
daystringThe day to read, as YYYY-MM-DD in UTC.
curl "https://api.nucleus-ai.io/v1/audit-log?event_type=checkpoints&day=2026-07-27" \
-H "Authorization: Bearer $NUCLEUS_API_KEY"{
"entries": [
{
"timestamp": "2026-07-27T09:14:02Z",
"event": "checkpoint.published",
"actor": "key_2Fd",
"path": "nucleus://run_3Bz:train:0/sampler_weights/000240"
}
]
}