Usage API
The customer-facing usage API lives under /admin/metrics/usage. It supports the dashboard's AI usage view. All three operations are read-only, are scoped to your tenant, and require the configuration read permission. Other admin metrics (findings, pull requests, tickets) are in Findings, Events and Metrics; the rest of the Admin API is indexed on Admin.
GET /admin/metrics/usage/ledger
Inspect paginated per-run usage records.
GET /admin/metrics/usage/aggregate
Aggregate cost and token totals by agent and class over a window.
GET /admin/metrics/usage/timeseries
Read daily or hourly cost and token buckets.
Time parameters (from, to) are RFC 3339 timestamps; the aggregate and time series return 400 for an unparsable value. Keep the time range and the agent and class filters identical when comparing an aggregate with a time series. Recorded model usage is not necessarily the final invoice or your remaining entitlement; contact Nullify for billing terms.
Usage ledger
Returns the per-run ledger entries for your tenant, one row per recorded agent run. Filter with from, to, agent, class, branchType, runId, and repeated findingId parameters to find the runs that spent usage on specific findings. Results are paginated: when the response includes nextToken, pass that value back as the cursor query parameter to fetch the next page. limit defaults to 50 when omitted. The request parameter is named cursor while the response field is nextToken; see Pagination for the general pattern.
Paginated per-run billing ledger entries for a tenant
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
GET /admin/metrics/usage/ledger HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"entries": [
{
"agent": "text",
"at": "text",
"branchType": "text",
"budgetKeys": [
"text"
],
"class": "text",
"commitSha": "text",
"entryId": "text",
"environment": "text",
"findingId": "text",
"llm": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"notes": "text",
"prNumber": 1,
"projectId": "text",
"repo": "text",
"runId": "text",
"status": "text",
"trigger": "text",
"usd": 1
}
],
"nextToken": "text"
}Usage aggregate
Returns cost (USD), run count, and input and output token totals grouped by agent and class. window is DAY, WEEK, MONTH (default), or YEAR, case-insensitive; any other value returns 400. If you omit to it is the current time, and if you omit from it is 30 days before to. Optional agent and class filters narrow the groups. The response includes the window used and an asOf timestamp.
Cost and token totals grouped by agent/class for a tenant
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
GET /admin/metrics/usage/aggregate HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"asOf": "text",
"totals": [
{
"group": {
"agent": "text",
"branchType": "text",
"class": "text"
},
"inputTokens": 1,
"outputTokens": 1,
"runCount": 1,
"usd": 1
}
],
"window": "text"
}Usage time series
Returns cost and token buckets over time. granularity is day (default) or hour; any other value returns 400. As with the aggregate, to defaults to now and from defaults to 30 days before to. Optional agent and class filters apply. The response echoes the resolved granularity, from, and to along with the buckets. Hourly queries over long ranges return many buckets, so narrow the range for hourly data.
Daily or hourly cost and token aggregation for a tenant
The Azure organization ID
The Bitbucket workspace ID
The Github owner ID
The GitLab group ID
The Nullify installation ID
Filter by Azure repository IDs
Filter by GitHub repository IDs
Filter by GitHub team ID
Filter by Bitbucket repository IDs
OK
Bad Request
Unauthorized
Forbidden
Internal Server Error
GET /admin/metrics/usage/timeseries HTTP/1.1
Host: api.<TENANT>.nullify.ai
Accept: */*
{
"buckets": [
{
"agent": "text",
"class": "text",
"inputTokens": 1,
"outputTokens": 1,
"timestamp": "text",
"usd": 1
}
],
"from": "text",
"granularity": "text",
"to": "text"
}Last updated