Consum și chei

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.

ConsumCopiază linkul secțiunii

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 eticheteCopiază linkul secțiunii

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.

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']);

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"])

curl -X GET 'https://ai.codai.ro/v1/usage'

{  "from": "2019-08-24",  "to": "2019-08-24",  "group_by": "day",  "data": [    {      "key": "string",      "requests": 0,      "errors": 0,      "tasks": 0,      "prompt_tokens": 0,      "completion_tokens": 0,      "cached_read_tokens": 0,      "cost_micro_usd": "string"    }  ]}

curl -X GET 'https://ai.codai.ro/v1/keys'

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "label": "string",      "prefix": "string",      "enabled": true,      "kind": "device",      "app": "string",      "device_id": "string",      "platform": "string",      "client_version": "string",      "tags": [        "string"      ],      "created_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "idle_expiry_days": 0,      "revoked_at": "2019-08-24T14:15:22Z",      "current": true    }  ]}

curl -X PATCH 'https://ai.codai.ro/v1/keys/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{  "tags": [    "string"  ]}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "tags": [    "string"  ]}