curl --request GET \
--url https://api.nano-gpt.com/api/v1/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.nano-gpt.com/api/v1/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.nano-gpt.com/api/v1/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nano-gpt.com/api/v1/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.nano-gpt.com/api/v1/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.nano-gpt.com/api/v1/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nano-gpt.com/api/v1/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "usage",
"scope": "current_key",
"apiKey": {
"id": 123
},
"from": "2026-05-01",
"to": "2026-05-31",
"timezone": "UTC",
"groupBy": "day,model",
"asOf": "2026-05-31T12:00:00.000Z",
"source": {
"rollupDays": [
"2026-05-01"
],
"liveDays": [
"2026-05-31"
],
"missingRollupDays": []
},
"totals": {
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
},
"byDay": [
{
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
}
],
"byModel": [
{
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
}
],
"byDayModel": [
{
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
}
]
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}Usage
Retrieve aggregate spend, request, and token usage for the authenticated API key
curl --request GET \
--url https://api.nano-gpt.com/api/v1/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.nano-gpt.com/api/v1/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.nano-gpt.com/api/v1/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nano-gpt.com/api/v1/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.nano-gpt.com/api/v1/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.nano-gpt.com/api/v1/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nano-gpt.com/api/v1/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"object": "usage",
"scope": "current_key",
"apiKey": {
"id": 123
},
"from": "2026-05-01",
"to": "2026-05-31",
"timezone": "UTC",
"groupBy": "day,model",
"asOf": "2026-05-31T12:00:00.000Z",
"source": {
"rollupDays": [
"2026-05-01"
],
"liveDays": [
"2026-05-31"
],
"missingRollupDays": []
},
"totals": {
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
},
"byDay": [
{
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
}
],
"byModel": [
{
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
}
],
"byDayModel": [
{
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356,
"date": "2026-05-01",
"model": "GPT-4.1 mini"
}
]
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}Overview
The Usage API returns bounded aggregate usage for the API key used to authenticate the request. Use it to answer:- What did this API key spend?
- Which models was that spend on?
- How many requests and tokens were used?
- What happened over a specific UTC date range?
X-Request-ID and the same inference API key. That lookup has
a rolling 24-hour window and returns the original primary charge; it does not
subtract refunds or include separately billed extras.
Base URL
https://api.nano-gpt.com/api/v1/usage
Authentication
Use the same NanoGPT API key authentication as other API routes:Authorization: Bearer $NANOGPT_API_KEY
curl "https://api.nano-gpt.com/api/v1/usage" \
-H "Authorization: Bearer $NANOGPT_API_KEY"
Default Request
If no date range is provided, the endpoint returns the authenticated API key’s last 30 UTC days, grouped by both day and model.curl "https://api.nano-gpt.com/api/v1/usage" \
-H "Authorization: Bearer $NANOGPT_API_KEY"
Date Ranges
Usefrom and to to request an explicit UTC date range. Both values must be YYYY-MM-DD dates. to is inclusive.
curl "https://api.nano-gpt.com/api/v1/usage?from=2026-05-01&to=2026-05-31" \
-H "Authorization: Bearer $NANOGPT_API_KEY"
fromandtomust be provided together.tomust be on or afterfrom.tocannot be in the future.- Ranges are capped at 366 days.
- All dates are interpreted in UTC.
Grouping
Usegroup_by to control which aggregate arrays are returned.
| Value | Returned arrays |
|---|---|
day | byDay |
model | byModel |
day,model | byDay, byModel, byDayModel |
day,model is the default. model,day is accepted as an alias for day,model.
Example:
curl "https://api.nano-gpt.com/api/v1/usage?from=2026-05-01&to=2026-05-31&group_by=model" \
-H "Authorization: Bearer $NANOGPT_API_KEY"
Scope
The endpoint is scoped to the authenticated API key.| Parameter | Default | Notes |
|---|---|---|
scope | current_key | current_key and api_key both return the authenticated API key’s usage. |
api_key_id | current key | Optional current API key ID. Requests for another API key are rejected. |
Response Shape
{
"object": "usage",
"scope": "current_key",
"apiKey": {
"id": 123
},
"from": "2026-05-01",
"to": "2026-05-31",
"timezone": "UTC",
"groupBy": "day,model",
"asOf": "2026-05-31T12:00:00.000Z",
"source": {
"rollupDays": ["2026-05-01"],
"liveDays": ["2026-05-31"],
"missingRollupDays": []
},
"totals": {
"requests": 1284,
"costUsd": 42.18,
"refundedUsd": 1.25,
"netCostUsd": 40.93,
"inputTokens": 1234567,
"outputTokens": 456789,
"reasoningTokens": 12000,
"totalTokens": 1691356
},
"byDay": [
{
"date": "2026-05-01",
"requests": 61,
"costUsd": 1.94,
"refundedUsd": 0,
"netCostUsd": 1.94,
"inputTokens": 78000,
"outputTokens": 21000,
"reasoningTokens": 0,
"totalTokens": 99000
}
],
"byModel": [
{
"model": "GPT-4.1 mini",
"requests": 812,
"costUsd": 18.92,
"refundedUsd": 0.5,
"netCostUsd": 18.42,
"inputTokens": 900000,
"outputTokens": 220000,
"reasoningTokens": 0,
"totalTokens": 1120000
}
],
"byDayModel": [
{
"date": "2026-05-01",
"model": "GPT-4.1 mini",
"requests": 20,
"costUsd": 0.64,
"refundedUsd": 0,
"netCostUsd": 0.64,
"inputTokens": 30000,
"outputTokens": 8000,
"reasoningTokens": 0,
"totalTokens": 38000
}
]
}
Field Reference
Top-level fields:| Field | Description |
|---|---|
object | Always usage. |
scope | Echoes the requested scope, either current_key or api_key. |
apiKey.id | Numeric ID of the authenticated API key. |
from | UTC start date. |
to | UTC end date, inclusive. |
timezone | Always UTC. |
groupBy | The effective grouping mode. |
asOf | Timestamp when the aggregate response was generated. Cached responses can be up to 60 seconds old. |
source.rollupDays | Days served from precomputed daily rollups. |
source.liveDays | Days served from live aggregation. Usually today or days not rolled up yet. |
source.missingRollupDays | Closed UTC days that were not available in the rollup table and had to be served live. |
| Field | Description |
|---|---|
requests | Number of billable usage requests in the aggregate bucket. |
costUsd | Gross USD usage cost before refunds. |
refundedUsd | USD amount refunded in the aggregate bucket. |
netCostUsd | max(0, costUsd - refundedUsd) for that aggregate bucket. |
inputTokens | Input tokens counted for the bucket. |
outputTokens | Output tokens counted for the bucket. |
reasoningTokens | Reasoning tokens counted separately when available. |
totalTokens | inputTokens + outputTokens. Reasoning tokens are reported separately and are not added to totalTokens. |
modelvalues are public model labels.- Internal routing providers are not exposed.
- Variants that share the same public label may be combined under that label.
Refund Notes
Refunds are applied at each returned aggregation level with:netCostUsd = max(0, costUsd - refundedUsd)
byModel or byDayModel rows may differ slightly from totals.netCostUsd when refunds cross buckets.
Errors
Errors use the standard NanoGPT API error shape:{
"error": {
"message": "from and to must use YYYY-MM-DD UTC dates.",
"type": "invalid_request_error"
}
}
| Status | Type | Meaning |
|---|---|---|
400 | invalid_request_error | Invalid date range, unsupported parameter, invalid grouping, or request for a different API key. |
401 | missing_api_key / invalid_api_key | Missing or invalid API key. |
429 | rate_limit_exceeded | Too many usage requests. |
503 | usage_not_ready | The requested range needs rollup data that is not ready yet. Try a shorter range or retry after rollup sync completes. |
503 | service_unavailable | Usage API temporarily unavailable. |
500 | server_error | Unexpected usage retrieval failure. |
Legacy Parameter Behavior
The usage endpoint is aggregate-first and rejects legacy row-history parameters. Rejected legacy parameters include:durationpagepageSizesortdirfilterweekOffsettzinclude_summary
from and to dates instead.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
UTC start date in YYYY-MM-DD format. Must be provided together with to.
"2026-05-01"
UTC end date in YYYY-MM-DD format, inclusive. Must be on or after from and cannot be in the future.
"2026-05-31"
Controls which aggregate arrays are returned. model,day is accepted as an alias for day,model.
day, model, day,model, model,day "day,model"
Usage scope. current_key and api_key both return usage for the authenticated API key.
current_key, api_key Optional current API key ID. Requests for another API key are rejected.
123
Response
Aggregate usage for the authenticated API key
Always usage.
usage Echoes the requested usage scope.
current_key, api_key Show child attributes
Show child attributes
UTC start date.
"2026-05-01"
UTC end date, inclusive.
"2026-05-31"
Always UTC.
UTC The effective grouping mode.
day, model, day,model "day,model"
Timestamp when the aggregate response was generated. Cached responses can be up to 60 seconds old.
"2026-05-31T12:00:00.000Z"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Returned when grouped by day.
Show child attributes
Show child attributes
Returned when grouped by model.
Show child attributes
Show child attributes
Returned when grouped by both day and model.
Show child attributes
Show child attributes