> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetokenless.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost and usage

> See exactly what a request cost, how much credit remains, and where spend is going.

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`.

<CardGroup cols={2}>
  <Card title="Account position" icon="wallet" href="#account-position">
    Read available credit, scoped grants, and the latest upstream usage events.
  </Card>

  <Card title="One routed request" icon="route" href="#one-routed-request">
    Use `X-Request-Id` to see total cost, selected model, and candidate ranking.
  </Card>
</CardGroup>

<Note>
  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.
</Note>

## 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.

<CodeGroup>
  ```sh cURL theme={"dark"}
  curl "https://api.usetokenless.com/v1/usage?limit=20" \
    -H "Authorization: Bearer $TOKENLESS_API_KEY"
  ```

  ```ts JavaScript theme={"dark"}
  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;
  ```
</CodeGroup>

| Field             | Meaning                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `limit_nanos`     | The account credit ceiling.                                                                 |
| `used_nanos`      | Credit 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?

```sh theme={"dark"}
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

<Tip>
  `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.
</Tip>

[Open the request-cost endpoint reference →](/api-reference/request)

## Explore routed requests

<CardGroup cols={3}>
  <Card title="Historical requests" icon="clock" href="#historical-requests">
    `GET /v1/usage/requests` is cursor-paginated and works well for activity feeds.
  </Card>

  <Card title="Session totals" icon="layers" href="#session-totals">
    Group coding-agent work by session and fetch aggregate cost/request count.
  </Card>

  <Card title="Feedback" icon="message-square" href="#rate-a-request">
    Attach thumbs and structured cost/quality feedback to a completed request.
  </Card>
</CardGroup>

### 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

| Endpoint                               | Use it for                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------ |
| `GET /v1/usage/sessions?ids=a,b,c`     | Aggregate `request_count` and `total_cost_nanos` for up to 100 known sessions.       |
| `GET /v1/usage/sessions/list?limit=30` | Discover 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.