# Usage & keys (/docs/api/gateway/usage-keys)

Your own usage split by day, key, device, app, platform, model, client or tag, and your API keys with device attribution and tags.

These routes return the same data the hub shows on its usage and keys pages, scoped to the account that owns the calling key. Use them from scripts, the SDKs, the CLI or an agent to answer "what did this machine cost me last week?" without opening the hub.

## Usage [#usage]

`GET /v1/usage` returns one row per value of `group_by` (`day` by default) for a window of UTC days. `from` and `to` are inclusive `YYYY-MM-DD` dates; without them you get the last 30 days including today. A window may be at most 400 days long.

- **Group by** `day`, `key`, `device`, `app` (OAuth client), `platform`, `model`, `client` or `tag`.
- **Filter** with `key`, `device`, `app`, `platform`, `model` or `tag`; filters apply before grouping, so `group_by=model&device=<id>` is "which models did this device use".
- **Columns**: `requests`, `errors`, `tasks` (tasks started), `prompt_tokens`, `completion_tokens`, `cached_read_tokens` and `cost_micro_usd` — USD micros as a decimal string (`"1250000"` = 1.25 USD). Divide by 1 000 000 for dollars; never parse it as a float if you sum many rows.
- **MCP.** Agents call the read-only tool `usage_get` (`days` = window ending today, default 30; optional `group_by`). There is no keys tool on the MCP server: keys stay in the hub, SDKs and CLI.
- **History.** The last 30 days are read from raw usage events; older days come from a daily rollup. Tags live on the key and are joined when you read, so tagging a key re-attributes its whole history.

## Keys and tags [#keys-and-tags]

`GET /v1/keys` lists your keys (add `include_revoked=true` for revoked ones). Each key carries its `kind` (`device`, `user`, `app`, `service`), the `device_id` and `platform` it was minted on, `client_version`, `tags`, timestamps and `current: true` for the key making the call. The secret is never returned. Keys minted for third-party apps are not listed.

`PATCH /v1/keys/{id}` replaces the tags of one key: at most 16 tags of up to 32 characters each, `[]` clears them. Tags are yours to define — a project, a client, a cost centre — and then `GET /v1/usage?group_by=tag` splits spend along them.

```ts
import { Codai } from 'codai-sdk';

const codai = new Codai({ apiKey: process.env.CODAI_API_KEY! });
const byDevice = await codai.usage.get({ from: '2026-09-01', to: '2026-09-30', group_by: 'device' });
const { data: keys } = await codai.keys.list();
await codai.keys.setTags(keys[0]!.id, ['client-acme']);
```

```python
from codai import Codai

codai = Codai(api_key="codai_...")
by_model = codai.usage.get({"group_by": "model"})
keys = codai.keys.list(include_revoked=True)["data"]
codai.keys.set_tags(keys[0]["id"], ["client-acme"])
```

<OpenAPIPage document="./openapi/en/gateway.yaml" operations={[{path: '/v1/usage',method: 'get'},{path: '/v1/keys',method: 'get'},{path: '/v1/keys/{id}',method: 'patch'}]} />