Usage

Every response tells you what it cost you in tokens. One endpoint tells you what is left on your key.

Figures on this page are illustrative: they show how a bill is worked out, not what any model costs today. Current prices are on Pricing.

What a response reports

Every reply carries a usage block.

"usage": {
  "input_tokens": 12,
  "cache_creation_input_tokens": 1204,
  "cache_read_input_tokens": 0,
  "cache_creation": {"ephemeral_5m_input_tokens": 1204, "ephemeral_1h_input_tokens": 0},
  "output_tokens": 33
}

When streaming

Usage arrives in two pieces, and the first one is incomplete.

Read the output count from message_delta. A client that reads usage only from message_start records one output token for every streamed call.

Telling a cache hit from a cache write

Send a stable prefix with a cache breakpoint on it:

"messages": [{"role": "user", "content": [
  {"type": "text", "text": "<your long stable prefix>",
   "cache_control": {"type": "ephemeral"}},
  {"type": "text", "text": "<the part that changes>"}
]}]

Then read the numbers back:

• cache_creation_input_tokens > 0 — a write. You paid 1.25× to fill the cache.
• cache_read_input_tokens > 0 — a hit. You paid 0.10×.

Where each model runs

claude-opus-5 is served from different capacity than the other six models, and is metered differently as a result.

It counts input tokens more generously. For English prose we measure about 1.67× the token count you would expect, plus a fixed overhead of roughly 530 tokens on every request. For Chinese and for code we have measured a higher per-unit count but have not yet pinned down the ratio, so treat it as at least 1.67× and measure your own traffic.

Checking your balance

GET /v1/usage reports your account’s text and video spend, balance, held credit and available credit in USD.

curl https://api.nightferry.io/v1/usage \
  -H "x-api-key: $NIGHTFERRY_KEY"

{
  "currency": "USD",
  "spend_usd": "0.163654",
  "balance_usd": "14.666346",
  "text_spend_usd": "0.026351",
  "video_spend_usd": "0.137303",
  "held_usd": "0.171631",
  "available_usd": "14.494715",
  "limit_usd": "14.830000",
  "key_spend_usd": "0.163654",
  "key_remaining_usd": "14.666346",
  "models": ["claude-opus-4-6", "..."]
}

It answers for the account owning the key in the header. Key budget fields describe that key alone.

models is what your key is allowed to call. That is not the same as what we can serve right now — a model on this list can still return a no-capacity error, and the price page lists only the models we have most recently seen working. If a model is missing from your models list, your key cannot call it at all, and that is a question for us rather than a capacity problem.

Amounts are USD strings with six decimal places; no exchange rate applies. The balance matches Console: granted credit minus posted text and video charges. Available credit is balance minus outstanding holds. Negative or insufficient available credit blocks new paid calls, while reads and funding remain available. limit_usd, key_spend_usd and key_remaining_usd describe this key; remaining budget is before its holds and constrains text requests only. Video uses account available credit. When no valid text budget is set, limit_usd and key_remaining_usd are null; balance reads still work. This changes the former key-only meaning of spend_usd and balance_usd. The former *_cny fields and fx object have been removed.

What we do not offer

/v1/messages/count_tokens exists in the Anthropic API but is not served here. We do not serve it, and the count we could return would ignore your tools and system blocks — on a real agent payload that is wrong by more than thirty times. A wrong number that looks right is worse than no number, so it returns 404.

To size a prompt before sending it, send it and read usage back. Failed requests are not billed — see Errors.