Usage - NanoGPT API Documentation

cURL

curl --request GET \
  --url https://nano-gpt.com/api/v1/usage \
  --header 'Authorization: Bearer <token>'

{
  "apiKey": {
    "id": 123
  },
  "from": "2026-05-01",
  "to": "2026-05-31",
  "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"
    }
  ]
}

GET

usage

cURL

curl --request GET \
  --url https://nano-gpt.com/api/v1/usage \
  --header 'Authorization: Bearer <token>'

{
  "apiKey": {
    "id": 123
  },
  "from": "2026-05-01",
  "to": "2026-05-31",
  "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"
    }
  ]
}

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?

The endpoint returns aggregate usage only. It does not return raw transaction rows, request payloads, prompts, responses, provider routing details, or account-wide usage across multiple API keys.

Base URL

https://nano-gpt.com/api/v1/usage

Authentication

Use the same NanoGPT API key authentication as other API routes:

Authorization: Bearer $NANOGPT_API_KEY

Example:

curl "https://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://nano-gpt.com/api/v1/usage" \
  -H "Authorization: Bearer $NANOGPT_API_KEY"

Date Ranges

Use from and to to request an explicit UTC date range. Both values must be YYYY-MM-DD dates. to is inclusive.

curl "https://nano-gpt.com/api/v1/usage?from=2026-05-01&to=2026-05-31" \
  -H "Authorization: Bearer $NANOGPT_API_KEY"

Rules:

from and to must be provided together.
to must be on or after from.
to cannot be in the future.
Ranges are capped at 366 days.
All dates are interpreted in UTC.

Grouping

Use group_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://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.

This endpoint does not return account-wide usage across all API keys.

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.

Usage counter fields:

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`.

Model fields:

model values 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)

Because net cost is floored per bucket, sums of 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"
  }
}

Common errors:

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:

duration
page
pageSize
sort
dir
filter
weekOffset
tz
include_summary

Use explicit UTC from and to dates instead.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

from

string<date>

UTC start date in YYYY-MM-DD format. Must be provided together with to.

Example:

"2026-05-01"

string<date>

UTC end date in YYYY-MM-DD format, inclusive. Must be on or after from and cannot be in the future.

Example:

"2026-05-31"

group_by

enum<string>

default:day,model

Controls which aggregate arrays are returned. model,day is accepted as an alias for day,model.

Available options:

day,

model,

day,model,

model,day

Example:

"day,model"

scope

enum<string>

default:current_key

Usage scope. current_key and api_key both return usage for the authenticated API key.

Available options:

current_key,

api_key

api_key_id

integer

Optional current API key ID. Requests for another API key are rejected.

Example:

123

Response

Aggregate usage for the authenticated API key

object

enum<string>

required

Always usage.

Available options:

usage

scope

enum<string>

required

Echoes the requested usage scope.

Available options:

current_key,

api_key

apiKey

object

required

Show child attributes

from

string<date>

required

UTC start date.

Example:

"2026-05-01"

string<date>

required

UTC end date, inclusive.

Example:

"2026-05-31"

timezone

enum<string>

required

Always UTC.

Available options:

UTC

groupBy

enum<string>

required

The effective grouping mode.

Available options:

day,

model,

day,model

Example:

"day,model"

asOf

string<date-time>

required

Timestamp when the aggregate response was generated. Cached responses can be up to 60 seconds old.

Example:

"2026-05-31T12:00:00.000Z"

source

object

required

Show child attributes

totals

object

required

Show child attributes

byDay

object[]

Returned when grouped by day.

Show child attributes

byModel

object[]

Returned when grouped by model.

Show child attributes

byDayModel

object[]

Returned when grouped by both day and model.

Show child attributes

Check Balance Create Invitation

Documentation Index

​Overview

​Base URL

​Authentication

​Default Request

​Date Ranges

​Grouping

​Scope

​Response Shape

​Field Reference

​Refund Notes

​Errors

​Legacy Parameter Behavior

Authorizations

Query Parameters

Response

Overview

Base URL

Authentication

Default Request

Date Ranges

Grouping

Scope

Response Shape

Field Reference

Refund Notes

Errors

Legacy Parameter Behavior