# Connecting usage

The ledger needs one thing from you: token metadata. Model names, token
counts, regions, timestamps. Never prompts, never completions; anything
content-shaped is rejected at the API boundary (see
[Security](/docs/security)).

There are three ways in, in order of preference. Exact credential
walkthroughs live inside the console (every tier, including preview
accounts, sees them); this page tells you what each path needs and what it
pulls.

## 1. Managed provider connections (preferred)

Paste one read-only credential per provider and the platform pulls daily
token aggregates automatically. Up to 50 distinct connections per account;
contact us beyond that. A daily auto-sync re-pulls a trailing three-day
window for every connection, replacing the window idempotently so provider
reporting lag never duplicates events.

### Anthropic (available)

- **Credential**: organization Admin API key (`sk-ant-admin…`), read-only,
  scoped to usage reporting.
- **What we pull**: daily tokens by model and service tier, with cache
  reads split out and counted at the cached-input discount. Extended
  thinking is billed inside output tokens by Anthropic, so nothing is
  hidden and no conservative multiplier fires.
- **Plans**: API organizations connect; Claude Pro or Max (consumer) has no
  usage API, so individuals self-report.

### OpenAI (available)

- **Credential**: organization Admin key (`sk-admin…`), read-only.
- **What we pull**: daily tokens by model, cached input reported
  separately, Batch API traffic mapped to the batch service tier. o-series
  reasoning is billed inside output tokens.
- **Plans**: API organizations connect; ChatGPT Plus or Pro has no usage
  API, so individuals self-report.

### Google (available)

- **Credential**: a service account JSON key holding only
  `roles/monitoring.viewer` on the Cloud project. Paste the whole file.
- **What we pull**: daily Vertex AI / Gemini token counts by model and
  region from Cloud Monitoring. This metric does not split out context
  cache reads or thinking tokens, so both are recorded as unreported,
  which fails toward conservatism in the estimate and the billable-token
  count rather than pretending they are zero.
- **Plans**: Cloud projects connect; the Gemini consumer app has no usage
  API, so individuals self-report.

### Rotation and removal

Re-adding a connection with the same label replaces its credential.
Removing a connection deletes the encrypted credential; usage already
ingested for closed periods is retained, because it is the billing and
estimate record.

## 2. The metering API

Push daily aggregates from your own gateway or infrastructure (OpenRouter,
LiteLLM, Bedrock, self-hosted models) with one authenticated call. Include
cached and reasoning token counts when you have them; omitted fields are
treated as unreported, never as zero. Full request and response shapes:
[metering API reference](/docs/metering-api).

## 3. Self-report in the console

No code, no credentials: enter monthly token totals straight from your
provider's usage dashboard or billing page. This is the right path for
individuals on consumer plans and for anyone evaluating before wiring a
connection. It is deliberately the least preferred source: connected data
is fresher, more granular, and harder to mistype. Self-reported figures are
recorded as customer-supplied, and the certificate states the token basis
of every period.

## Which path am I?

- **Personal**: usually self-report (consumer plans expose no usage APIs);
  the metering API if you build with API keys.
- **Team and Business**: managed connections for each API organization, the
  metering API for gateways and self-hosted models, self-report to fill
  gaps.
- **Enterprise**: managed connections plus a reviewed ingest plan across
  providers, gateways, and regions.