Skip to main content
Tokenless exposes cost at two useful levels: account position and routed request economics. All amounts are integer USD nanos—1_000_000_000 is $1.

Account position

Read available credit, scoped grants, and the latest upstream usage events.

One routed request

Use X-Request-Id to see total cost, selected model, and candidate ranking.
All usage endpoints accept the same API key or bearer authentication as model requests. They are intentionally available even when an account has no credit.

​
Account position

GET /v1/usage is the starting point for billing UI, account summaries, and a simple “how much did I spend?” view. It returns the credit ceiling and consumed credit plus recent provider-level cost events. 
curl "https://api.usetokenless.com/v1/usage?limit=20" \
  -H "Authorization: Bearer $TOKENLESS_API_KEY"

const response = await fetch("https://api.usetokenless.com/v1/usage?limit=20", {
  headers: { Authorization: `Bearer ${process.env.TOKENLESS_API_KEY}` },
});

const usage = await response.json();
const usedUsd = usage.used_nanos / 1_000_000_000;
FieldMeaning
limit_nanosThe account credit ceiling.
used_nanosCredit consumed so far.
grants[]Active credit grants, including their remaining amount and optional routing/provider scope.
recent_events[]Recent upstream model legs with token counts and cost_nanos.
Use limit to change the recent-event count. It defaults to 20 and caps at 200.

​
One routed request

Every model response includes X-Request-Id. Store it with your application trace, then use it to answer the questions users actually ask: what did this turn cost, which model answered, and which routing policy ran? 
curl "https://api.usetokenless.com/v1/usage/requests/$REQUEST_ID" \
  -H "Authorization: Bearer $TOKENLESS_API_KEY"
The request record has:
  • total_cost_nanos, total_input_tokens, and total_output_tokens
  • selected_model_id and provider_ranks
  • routing_mode (pro, max, or ultra_saver)
  • optional session_id, agent_id, and session_source fields for coding-agent workloads
byok: true means the request used a tenant provider key. Its displayed cost is useful for observability, but it is not necessarily fully charged to Tokenless credit.
Open the request-cost endpoint reference →

​
Explore routed requests

Historical requests

GET /v1/usage/requests is cursor-paginated and works well for activity feeds.

Session totals

Group coding-agent work by session and fetch aggregate cost/request count.

Feedback

Attach thumbs and structured cost/quality feedback to a completed request.

​
Historical requests

GET /v1/usage/requests returns { "items": [...], "has_more": true|false }. Pass both before (an RFC 3339 timestamp) and before_id from the last item to load an older page. Use session_id to restrict results to one session.

​
Session totals

EndpointUse it for
GET /v1/usage/sessions?ids=a,b,cAggregate request_count and total_cost_nanos for up to 100 known sessions.
GET /v1/usage/sessions/list?limit=30Discover recent sessions, ordered by latest activity. Default is 30; max is 100.

​
Rate a request

POST /v1/usage/requests/{request_id}/feedback records a thumbs rating or an optional comment. Include a structured reason such as too_expensive, too_slow, great_value, stronger_model_needed, or wrong_model to make cost/quality feedback useful for routing analysis.