GET/api/v1/credits

Histórico de créditos

Bearer tokenescopo read:usage

Consulta o saldo atual e o histórico de créditos da conta associada ao Bearer token. Responde 200 OK.

Escopo necessário: read:usage (ver Escopos).

Não confunda com POST /api/v1/credits, que cria uma order de compra de créditos via PIX e exige o escopo create:credits. Este endpoint (GET) apenas consulta saldo e histórico.

Query params

Parâmetro	Tipo	Default	Máximo	Descrição
`limit`	inteiro	`20`	`100`	Itens do histórico por página
`offset`	inteiro	`0`	`10000`	Quantos itens pular

Ver Paginação.

Exemplo de request

cURL

curl "https://avatrix.io/api/v1/credits?limit=20&offset=0" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx"

Resposta — 200

JSON

{
  "success": true,
  "data": {
    "balance": 1250,
    "history": [
      {
        "id": "clx...",
        "amount": -12,
        "reason": "generation",
        "toolId": "image-gen",
        "description": "Geração de imagem",
        "createdAt": "2026-06-18T12:34:56.000Z"
      },
      {
        "id": "clx...",
        "amount": 1000,
        "reason": "purchase",
        "toolId": null,
        "description": "Compra de pacote de créditos",
        "createdAt": "2026-06-17T09:00:00.000Z"
      }
    ],
    "limit": 20,
    "offset": 0
  }
}

balance é o saldo atual (nunca negativo). Em cada item do history, amount é positivo quando créditos entram (compra, bônus) e negativo quando são consumidos; toolId indica a ferramenta que consumiu, ou null quando não se aplica. O histórico vem ordenado do mais recente para o mais antigo.

Erros relevantes

Código	HTTP	Quando
`UNAUTHORIZED`	401	token ausente, inválido, expirado ou revogado
`FORBIDDEN`	403	token sem `read:usage`
`RATE_LIMITED`	429	rate limit (60 req/min por token), com `Retry-After`

Ver Erros.