> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.conductorquantum.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.conductorquantum.com/_mcp/server.

# Usage and credits

Coda bills the wallet a run was authorised against: the API-token account's personal wallet, or a **team wallet** when the run is billed to an Enterprise team (`billed_team_id`). One prompt is not one credit. A run reserves a hold, then settles from metered tokens.

These endpoints use the same bearer token as the rest of the Coda API. They accept `mcp:read` or `agents:run`. They are not available on the `/mcp` path.

## Hosts

Through the web application:

```text
https://<coda-host>/v0/coda/usage/...
```

On the deployed `coda-api` Modal URL the same routes are served without the `/coda` segment (`GET /v0/usage/...`). Send `X-API-Path: api` when calling Modal directly. The Next.js proxy adds this header for `/v0/*` requests.

## Remaining credits

`GET /usage/credits` returns remaining free and paid credits, the plan, and the billing period for the wallet this token bills. A personal token sees the personal wallet. A team service-account key sees that team's wallet.

```python
from conductorquantum import ConductorQuantum

client = ConductorQuantum(token="<your-api-key>")
balance = client.coda.usage.credits()
print(balance)
```

Example response:

```json
{
  "plan": "enterprise",
  "credits": {
    "free_remaining": 0.0,
    "paid_remaining": 997.54321,
    "remaining": 997.54321
  },
  "billing_period_start": "2026-08-01T00:00:00+00:00",
  "billing_period_end": "2026-09-01T00:00:00+00:00"
}
```

## Usage window

`GET /usage` returns the remaining balance plus AI usage in a window (default last 30 days):

* `daily[]` buckets for a last-30-days graph
* `teams[]` breakdown
* `untagged` for runs with no `team_id`
* recent `runs[]`

Query parameters:

* `since` / `until`: RFC 3339 timestamps. The window cannot exceed 90 days.
* `limit`: number of recent runs to include (1-200, default 50).

```python
summary = client.coda.usage.list()
print(summary.charged_credits, summary.tokens)
```

## Look up a run or thread

Store `X-Run-Id` and `X-Thread-Id` from `POST /agents`.

| Endpoint                         | Purpose                                                 |
| -------------------------------- | ------------------------------------------------------- |
| `GET /usage/runs/{run_id}`       | Post-hoc cost for one run (`X-Run-Id` / `job_id`)       |
| `GET /usage/threads/{thread_id}` | Post-hoc cost for every run on a thread (`X-Thread-Id`) |
| `GET /usage/teams/{team_id}`     | Post-hoc cost billed to one team                        |

```python
run = client.coda.usage.runs.get("<run-id>")
print(run.status, run.charged_credits)
```

Example per-run response:

```json
{
  "job_id": "11111111-1111-4111-8111-111111111111",
  "run_id": "11111111-1111-4111-8111-111111111111",
  "thread_id": "22222222-2222-4222-8222-222222222222",
  "team_id": "33333333-3333-4333-8333-333333333333",
  "billed_team_id": "33333333-3333-4333-8333-333333333333",
  "source": "public_agents_api",
  "status": "settled",
  "budget": "high",
  "requested_credits": 0.25,
  "billable_credits": 0.184321,
  "charged_credits": 0.184321,
  "tokens": {"prompt": 1200, "completion": 340, "total": 1540},
  "created_at": "2026-08-20T15:04:00+00:00",
  "settled_at": "2026-08-20T15:04:12+00:00"
}
```

> **Warning**
>
> `thread_id` is attached best-effort after authorisation. A run can still settle with `thread_id` null. Reconcile those rows from the account or team summary. Do not treat a thread rollup as the complete ledger.

## Charge fields

* `requested_credits` is the authorisation hold reserved when the run started.
* `billable_credits` is the metered settlement amount once pricing succeeds.
* `charged_credits` is what was deducted. Use this for 1:1 partner credit mapping after `status` is `settled` or `debt`. The public API does not expose the internal rate formula.
* `tokens.prompt` / `tokens.completion` are the settled input and output token totals.
* `billed_team_id` is the team wallet that was debited. It is null on personal-wallet runs.
* `authorized` or `pricing_pending` means the final charge is not ready yet. Poll the same URL. `released` means the hold was refunded.

Usage rows include `team_id` / `billed_team_id`, `source`, and run/thread ids. Where a roster or callback includes `user_id`, that is the actor. API-token identity is not stored on usage rows.

## Dashboard

A signed-in user on the representative account can review remaining credits, a usage chart, the credit ledger, and a last-30-days usage-by-team table under **Settings → Billing**. Per-team attributed queries and CSV export live on [Settings → Teams](/coda/usage/teams-and-team-wallets#usage).

## Related endpoints

* `GET /usage/credits`: remaining balance
* `GET /usage`: windowed usage and daily buckets
* `GET /usage/runs/{run_id}`: one run
* `GET /usage/threads/{thread_id}`: one thread
* `GET /usage/teams/{team_id}`: one team

See the [Coda API Reference](/api-reference/coda-api) for full schemas. For push delivery, see [Usage callbacks](/coda/usage/usage-callbacks).