GET

/v1/usage

API reference

Account charge history, newest first, with cursor pagination. Requires a key; the request is free.

1Request example

bash

curl -G https://api.zukko.pro/v1/usage \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  --data-urlencode "limit=50"

2Parameters

Parameter	Type	Description
`limit`	int	records per page, 1 to 100, default 20
`cursor`	string	the `next_cursor` value from the previous response

3Response

json

{
  "data": [
    {
      "created_at": "2026-10-01T12:00:00+00:00",
      "model": "Claude Sonnet 5",
      "input_tokens": 1500,
      "output_tokens": 320,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "total_tokens": 1820,
      "cost_cents": 0.0546
    }
  ],
  "next_cursor": "2026-10-01T11:59:00+00:00|48213"
}

Field	Type	Description
`created_at`	string	charge time, ISO 8601 in UTC
`model`	string	model display name (e.g. `Claude Sonnet 5`) or a service name such as `web-search`
`input_tokens`	int	input tokens, cache included
`output_tokens`	int	output tokens (for images — the number of images)
`cache_read_tokens`	int	part of the input read from the cache
`cache_write_tokens`	int	part of the input written to the cache
`total_tokens`	int	input plus output
`cost_cents`	float	cost in cents with a fractional part: `0.0546` = $0.000546

4Pagination

The cursor looks like <time>|<numeric record id>. Pass next_cursor into cursor as is, but URL-encode it: it contains + and |, and an unencoded + turns into a space — then you get the first page again. curl -G --data-urlencode is the easiest way:

bash

curl -G https://api.zukko.pro/v1/usage \
  -H "Authorization: Bearer fetch_YOUR_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=2026-10-01T11:59:00+00:00|48213"

next_cursor: null means there are no more records.

5What is included

Every charge on the account, not just this key: other keys, the web chat, the Telegram bot, web search.
Responses from the Zukko cache and Idempotency-Key replays are free and do not appear in the history.

GET /v1/balance

Key limits, idempotency and caching