Billing API

Read what each request cost, page through request history, and check a key’s remaining limit, using the same API key you call models with.

Overview

Endpoint	Returns
`GET /v1/billing/requests`	Requests, newest first, with cost and token usage
`GET /v1/billing/requests/{id}`	One request, by its `x-token-share-request-id`
`GET /v1/billing/balance`	The key’s limit and usage; the account balance for CLI keys

Authenticate exactly as for /v1: Authorization: Bearer or x-api-key. What a key can see depends on its type:

Key type	Sees	`scope` in responses
Inference	Only requests made with this key, and this key’s limit	`key`
CLI	Every request on the account, and the account balance	`account`

Responses are cache-control: private, no-store. Amounts are in USD.

List requests

GET /v1/billing/requests returns requests newest first. Without since or until it covers the last 24 hours, and range in the response says which window was applied.

Query	Meaning
`since`	ISO 8601 date or timestamp. A bare date (`2026-10-01`) starts at 00:00 UTC.
`until`	ISO 8601 date or timestamp. A bare date runs to the end of that UTC day.
`page`	From 1. Default 1.
`page_size`	Default 50, at most 200.

curl "https://token-share.app/v1/billing/requests?since=2026-10-01&until=2026-10-07&page_size=100" \
  -H "Authorization: Bearer $TOKEN_SHARE_KEY"

Field	Meaning
`id`	The request id; the same value as the `x-token-share-request-id` response header.
`key_id`	The key that made the request.
`cost_usd`	What you were charged. `0` for a request that was not billed.
`payment_status`	`paid`: taken from your wallet. `unpaid`: billed, but the wallet could not cover it. `unbilled`: usage could not be measured, nothing charged.
`payment_source`	Which of your wallets paid: `balance` (top-ups), `earned` (contribution earnings) or `promo` (promotional credit).
`usage`	Input, output, cache-read and cache-creation tokens.
`total`, `total_cost_usd`	Count and total charge over the whole window, not just this page.

Get one request

GET /v1/billing/requests/{id} takes the x-token-share-request-id from any /v1 response. It returns the same fields as the list, plus:

Field	Meaning
`list_price_usd`	The same usage at the model’s official list price, so the discount is visible.
`failure_reason`	For a failed request, a short machine-readable reason.
`fallback_from_model`, `fallback_reason`	Present when the request was served on another lane: the model you asked for, and why. `model` is the one that served and priced it.

curl https://token-share.app/v1/billing/requests/6f1c2a8e-3b4d-4f7a-9c1e-2d5b8a0f7e31 \
  -H "Authorization: Bearer $TOKEN_SHARE_KEY"

An id that does not exist, belongs to another account, or (for an inference key) was made by another key all return the same 404 {"error": "not_found"}. A lookup right after a response ends can also return 404 until the record is written; retry after a few seconds.

Balance and limits

GET /v1/billing/balance returns this key’s limit and how much of it is used. limit_usd and remaining_usd are null when the key has no limit of its own. account is the account’s spendable balance, returned to CLI keys only; it is null for an inference key.

curl https://token-share.app/v1/billing/balance \
  -H "Authorization: Bearer $TOKEN_SHARE_KEY"

Errors

Status	When
`400`	`since` or `until` is not a date.
`401`	Missing, unknown, revoked or expired key.
`404`	No request with that id that this key can see.
`503`	The key could not be checked right now. Retry.