# API de créditos

> GET /v1/credits retorna o saldo da organização e o gasto e os orçamentos da chave usada na chamada.


Consulte seu saldo sem gastar nada. A chamada é gratuita e não reserva nada.

```endpoint
GET https://api.notholy.com/v1/credits
```

```bash test
curl https://api.notholy.com/v1/credits -H "Authorization: Bearer $NOTHOLY_API_KEY"
```

## Resposta

```json
{
  "object": "credits",
  "currency": "USD",
  "balance": "24.913402",
  "reserved": "0.004000",
  "available": "24.909402",
  "key": { "spent": "0.086598", "daily_budget": "5.000000" }
}
```

| Campo | Tipo | Observações |
|---|---|---|
| `object` | string | Sempre `credits` |
| `currency` | string | Sempre `USD` |
| `balance` | string | Créditos menos o uso já cobrado |
| `reserved` | string | Reservado agora por requisições em andamento. Cada reserva é o custo de pior caso da requisição; a parte não usada volta quando ela é liquidada |
| `available` | string | O que uma nova requisição pode reservar: `balance` menos `reserved` |
| `key.spent` | string | Total gasto com esta chave |
| `key.total_budget`, `key.daily_budget` | string | Aparecem quando a chave tem orçamento |

Os valores são strings decimais com 6 casas. Dentro da NotHoly eles são inteiros em bilionésimos de dólar, então não há arredondamento entre uma requisição e outra.

> [!NOTE]
> Toda requisição reserva o seu pior caso (prompt mais `max_tokens`) antes de começar. Quando `available` é menor que isso, o limite de saída diminui para caber, e abaixo de 16 tokens a requisição retorna `402 insufficient_credits`. Confira `available` antes de gerações longas.

```js test
const r = await fetch('https://api.notholy.com/v1/credits', { headers: { Authorization: `Bearer ${process.env.NOTHOLY_API_KEY}` } });
const c = await r.json();
console.log(c.available);
```

## Erros

| Status | Código | Significado |
|---|---|---|
| 401 | `invalid_api_key` | Chave ausente, inválida, revogada ou expirada |
| 500 | `internal_error` | Não foi possível ler o saldo. Tente de novo com backoff |