curl --request GET \
--url https://nano-gpt.com/api/subscription/v1/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/v1/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://nano-gpt.com/api/subscription/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{
"active": true,
"state": "active",
"limits": {
"dailyInputTokens": 123,
"weeklyInputTokens": 123,
"dailyImages": 123
},
"dailyInputTokens": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"weeklyInputTokens": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"dailyImages": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"period": {
"currentPeriodEnd": "2023-11-07T05:31:56Z"
},
"tokens": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"usageUnits": "tokens",
"tokenLimits": {
"total": 123
},
"routing": {
"recommendedMode": "subscription",
"reason": "<string>",
"subscriptionQuotaAvailable": true,
"paidSpendPolicyAllowsBalance": true
}
}Subscription Usage
Read subscription token quotas and billing-routing advice for your inference API key.
curl --request GET \
--url https://nano-gpt.com/api/subscription/v1/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/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://nano-gpt.com/api/subscription/v1/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://nano-gpt.com/api/subscription/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{
"active": true,
"state": "active",
"limits": {
"dailyInputTokens": 123,
"weeklyInputTokens": 123,
"dailyImages": 123
},
"dailyInputTokens": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"weeklyInputTokens": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"dailyImages": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"period": {
"currentPeriodEnd": "2023-11-07T05:31:56Z"
},
"tokens": {
"used": 123,
"remaining": 123,
"percentUsed": 123,
"resetAt": 123,
"degraded": true
},
"usageUnits": "tokens",
"tokenLimits": {
"total": 123
},
"routing": {
"recommendedMode": "subscription",
"reason": "<string>",
"subscriptionQuotaAvailable": true,
"paidSpendPolicyAllowsBalance": true
}
}Choose the right credential
For a quota widget or monitoring script, use a Usage only management token. It can read subscription quotas without permission to run models or spend your balance. This endpoint uses an inference API key and also returns billing-routing advice specific to that key. Management tokens are accepted only atGET /api/management/v1/subscription/usage.
Request
- Method:
GET - Path:
/api/subscription/v1/usage(alias:/api/v1/subscription/usage) - Auth:
Authorization: Bearer <api_key>orx-api-key: <api_key>
curl https://nano-gpt.com/api/subscription/v1/usage \
-H "Authorization: Bearer $NANOGPT_API_KEY"
Response
The response includesactive, state, limits, dailyInputTokens, weeklyInputTokens, dailyImages, period, and routing. See the quota example and field definitions for the shared usage fields. The inference-authenticated response also includes subscription metadata and allowOverage.
Input-token quotas count tokens, not operation counts or dollars. Image quotas count images. percentUsed is a fraction and may exceed 1. Quota resetAt values are UNIX epoch milliseconds; period.currentPeriodEnd is an ISO timestamp or null. Use returned limits and reset times instead of hardcoding them.
A null quota/limit is not configured or applicable. When a lookup is unavailable, counters are null with degraded: true. Display unknown, not a full allowance. Token-based trials also include usageUnits, tokenLimits, and tokens.
Billing-routing advice
Userouting.recommendedMode when choosing between included subscription usage and pay-as-you-go billing:
| Value | Meaning |
|---|---|
subscription | This key permits subscription billing and quota is available or temporarily unknown, rather than known to be exhausted |
paygo | Subscription use is unavailable or exhausted and the key’s policy permits paid-balance spending |
unavailable | Neither billing mode is usable under the known subscription and key policy |
routing.reason explains the recommendation. subscriptionQuotaAvailable is true, false, or null (unknown). The weekly routing calculation includes the service’s small enforcement allowance, so the displayed base quota can be exhausted before the recommendation switches to paid usage.
The advice checks billing policy and known subscription quotas. It does not check current cash balance, consumed non-zero request/spend caps, the cost of a particular request, or provider health. The generation endpoint remains authoritative. A configured zero daily request or input-token cap makes the recommendation unavailable.
active: true alone does not prove quota remains, and a zero cash balance does not prove included subscription tokens are exhausted. Use Check Balance separately when you need cash balances.
Clients can reuse advice briefly, but should refresh it after quota or billing errors. Never force a subscription-only key onto paid billing. Retain the NanoGPT request ID when reporting a transient billing issue.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Response
Subscription quotas and billing-routing advice. Unavailable counters are null with degraded=true.
active, grace, inactive Show child attributes
Show child attributes
Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.
Show child attributes
Show child attributes
Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.
Show child attributes
Show child attributes
Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.
Show child attributes
Show child attributes
Present for token-based trials.
tokens Present for token-based trials.
Show child attributes
Show child attributes
Inference-key-specific billing-policy advice. Does not check current balance, consumed nonzero spend/request caps, or provider health.
Show child attributes
Show child attributes