# Consum și chei (/ro/docs/api/gateway/usage-keys)

Consumul tău împărțit pe zi, cheie, dispozitiv, aplicație, platformă, model, client sau etichetă, plus cheile tale API cu atribuirea pe dispozitiv și etichete.

Aceste rute întorc aceleași date pe care le arată hub-ul în paginile de consum și de chei, limitate la contul care deține cheia apelantă. Folosește-le din scripturi, din SDK-uri, din CLI sau dintr-un agent ca să afli „cât m-a costat mașina asta săptămâna trecută?” fără să deschizi hub-ul.

## Consum [#consum]

`GET /v1/usage` întoarce câte un rând pentru fiecare valoare a lui `group_by` (implicit `day`) pe o fereastră de zile UTC. `from` și `to` sunt date `YYYY-MM-DD` incluse; fără ele primești ultimele 30 de zile, inclusiv azi. O fereastră are cel mult 400 de zile.

- **Grupare** după `day`, `key`, `device`, `app` (client OAuth), `platform`, `model`, `client` sau `tag`.
- **Filtre**: `key`, `device`, `app`, `platform`, `model` sau `tag`; filtrele se aplică înainte de grupare, deci `group_by=model&device=<id>` înseamnă „ce modele a folosit dispozitivul acesta”.
- **Coloane**: `requests`, `errors`, `tasks` (sarcini pornite), `prompt_tokens`, `completion_tokens`, `cached_read_tokens` și `cost_micro_usd` — micro-USD ca șir zecimal (`"1250000"` = 1,25 USD). Împarte la 1 000 000 pentru dolari; nu-l transforma în float dacă aduni multe rânduri.
- **MCP.** Agenții apelează unealta doar-citire `usage_get` (`days` = fereastra care se încheie azi, implicit 30; `group_by` opțional). Serverul MCP nu are unealtă pentru chei: cheile rămân în hub, SDK-uri și CLI.
- **Istoric.** Ultimele 30 de zile sunt citite din evenimentele brute de consum; zilele mai vechi vin dintr-o agregare zilnică. Etichetele stau pe cheie și sunt unite la citire, deci etichetarea unei chei îi reatribuie tot istoricul.

## Chei și etichete [#chei-și-etichete]

`GET /v1/keys` listează cheile tale (adaugă `include_revoked=true` pentru cele revocate). Fiecare cheie are `kind` (`device`, `user`, `app`, `service`), `device_id` și `platform` pe care a fost emisă, `client_version`, `tags`, marcajele de timp și `current: true` pentru cheia care face apelul. Secretul nu este returnat niciodată. Cheile emise pentru aplicații terțe nu apar.

`PATCH /v1/keys/{id}` înlocuiește etichetele unei chei: cel mult 16 etichete de până la 32 de caractere, iar `[]` le șterge. Etichetele le alegi tu — un proiect, un client, un centru de cost — iar apoi `GET /v1/usage?group_by=tag` împarte cheltuielile după ele.

```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/ro/gateway.yaml" operations={[{path: '/v1/usage',method: 'get'},{path: '/v1/keys',method: 'get'},{path: '/v1/keys/{id}',method: 'patch'}]} />