> Keiro Labs API documentation - Usage and Billing
> Page: https://docs.keirolabs.ai/usage-billing.html
> Markdown: https://docs.keirolabs.ai/usage-billing.md
> Agent index: https://docs.keirolabs.ai/llms.txt
> API base URL: https://api.keirolabs.ai/v1
> Auth: send "Authorization: Bearer <api-key>" with a key created in the
> Keiro console (https://console.keirolabs.ai/api-keys). Use credentials saved by
> `keiro setup`, or resolve the key from a secret manager or an owner-only
> secret file and pass it to the client explicitly. Never read another
> provider's variable, and never put raw key material in environment
> variables, code, docs, or logs.

# Usage and billing

Use the Keiro console to understand request volume, token usage, billable
amounts, limits, and account billing. API response headers remain authoritative
for the limits that applied to one request.

## Choose the right view

| Question | Console view | What it shows |
|---|---|---|
| How much have we used? | [Usage](https://console.keirolabs.ai/usage) | Requests, input and output tokens, failures, rate-limited requests, and spend over a selected window |
| Which model or key generated it? | Usage drilldowns | Request and token volume grouped by model or API key |
| What happened to one request? | [Logs](https://console.keirolabs.ai/logs) | Request ID, endpoint, model, status, token totals, latency, and safe error context |
| What are the current caps? | [Limits](https://console.keirolabs.ai/limits) | Organization limits plus narrower API-key overrides |
| What is the billing account state? | [Billing](https://console.keirolabs.ai/billing) | Subscription, payment method, invoices, adjustments, refunds, and usage export when available to your role |

The console scopes every view to the selected organization. Check that
organization before comparing totals or exporting data.

## Understand the numbers

Keiro reports canonical input and output token totals for the public model
request. When a completed request is billable, its billing record carries the
amount used for customer billing.

Billing records can be `pending` while completion or reconciliation is still
in progress and `finalized` after settlement. Recent totals can therefore move
from pending to finalized without representing a second request.

Request-log amounts are operational context. Use billing-record totals for
billable spend and invoices for the amount due. Customer-managed provider
credentials are not charged as Keiro per-token usage when the account's active
billing mode excludes that charge.

Hosted web search is billed per search request, separately from tokens. The
Keiro CLI and Console offer it by default and leave the decision to the
model; API callers only get it when they include the tool. Searched requests
show the search count alongside token totals in Logs, and the charge appears
in the billing record's amount.

## Prompt cache pricing

Effective 2026-08-08, prompt tokens served from a prompt cache are billed at
a discount on every public model. Rates are multiples of the model's standard
input rate:

| Token class | Rate |
|---|---|
| Input, uncached | 1x input rate |
| Input, cached read | 0.1x input rate |
| Input, cache write | 1x input rate (no write surcharge) |
| Output | 1x output rate |

The usage object already reports the cached portions of the prompt
(`cache_read_input_tokens` and `cache_creation_input_tokens` on the Messages
surface, `cached_tokens` details elsewhere); the discount applies to those
reported counts. No request change is needed — requests that reuse a cached
prompt prefix are billed the discounted amount automatically, and the billing
record's amount reflects it.

## Export usage

Use the console's CSV export for customer-safe billing records. Export rows can
include:

- record ID and non-secret API-key ID
- status
- input and output token totals
- hosted web search count, when the request searched
- billable amount
- creation and finalization timestamps

Exports do not include raw API keys, prompt or response bodies, private routing
details, provider credentials, or internal cost and margin data.

## Reconcile an application request

Keep the response request ID with your application's own operation ID. When you
investigate a discrepancy:

1. Match the request ID and timestamp in Logs.
2. Confirm the endpoint, requested public model, status, and token totals.
3. Check whether the associated billing record is pending or finalized.
4. Compare the active price and plan information in Billing.
5. Contact support with safe identifiers if the finalized record still does
   not match your expectation.

Do not send the API key or full prompt/response body in the first support
message.

## Limits and denials

Rate and spend limits are admission controls, not invoice totals. A request can
be denied before dispatch when it would exceed a configured limit. A `429`
response includes a machine-readable error and, when applicable,
`Retry-After`; waiting does not reset a daily or monthly spend cap early.

See [Rate and spend limits](rate-and-spend-limits.md) for header and retry
contracts.

## Related pages

- [API keys](api-keys.md)
- [Rate and spend limits](rate-and-spend-limits.md)
- [Errors](errors.md)
- [Data retention](data-retention.md)