API pública de faturamento

Consulte saldo da conta, uso de modelos e custos nos seus próprios sistemas de faturamento

A API pública de faturamento permite ler dados de faturamento do Atlas Cloud a partir de scripts, dashboards e sistemas financeiros.

Base URL: https://api.atlascloud.ai/public/v1

Endpoints

Endpoint	Descrição
`GET /balance`	Saldo atual da conta e resumo de créditos
`GET /model-usage`	Buckets diários de uso dos modelos
`GET /model-costs`	Buckets diários de custo dos modelos

Os schemas completos estão na referência da API:

Autenticação

Envie uma API Key do Atlas Cloud no header Authorization:

Authorization: Bearer apikey-...

Crie chaves em API Keys. A chave secreta começa com apikey-.

Algumas respostas e filtros usam um API Key public ID como ak_.... Esse ID pode aparecer em relatórios de faturamento, mas não é uma credencial.

Permissões

/model-usage e /model-costs usam scope=self por padrão e retornam o uso atribuído ao usuário autenticado, incluindo as API Keys que ele possui.

Use scope=account para consultar uso e custos da conta inteira. Esse scope requer account-level model billing read permission. /balance sempre usa account scope e requer account balance read permission.

Proprietários de contas pessoais podem ler seus próprios dados. Em contas de equipe, use um papel Account Admin ou Finance.

Consultar Saldo

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

Valores monetários são retornados como strings com seis casas decimais e moeda:

{
  "value": "125.500000",
  "currency": "usd"
}

Parâmetros de Uso e Custos

start_date e end_date são datas UTC obrigatórias no formato YYYY-MM-DD. end_date é exclusivo e o intervalo máximo é de 180 dias.

Parâmetros comuns de /model-usage e /model-costs. Omitir group_by[] retorna totais diários:

Parâmetro	Descrição
`start_date`	Data UTC inicial inclusiva no formato `YYYY-MM-DD`
`end_date`	Data UTC final exclusiva no formato `YYYY-MM-DD`; o intervalo pode cobrir no máximo 180 dias
`scope`	`self` ou `account`; padrão `self`
`group_by[]`	Agrupamento opcional. Conjuntos suportados: `model_type`, `model`, `api_key`, ou `model` mais `api_key`; use `group_by[]=model` para detalhar por modelo
`model_types[]`	Repita com `text`, `image` ou `video`
`model_ids[]`	Filtra por IDs de modelo; até 100 valores
`api_key_ids[]`	Filtra por public IDs `ak_...`; até 100 valores
`limit`	Linhas por página, de 1 a 1000; padrão 100
`page`	Cursor opaco recebido em `next_page`

Use parâmetros repetidos para arrays. Valores separados por vírgula são rejeitados.

Consultar Uso

A resposta padrão retorna totais diários de uso.

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

Consultar Custos

/model-costs aceita o mesmo intervalo de datas, scope, filtros, agrupamento e paginação que /model-usage. Omitir group_by[] retorna custos diários totais.

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

Paginação

Quando has_more for true, envie next_page sem alteração como parâmetro page. Trate o cursor como opaco e mantenha os demais parâmetros iguais.

Erros e Limites

Erros usam um envelope estável:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

Respostas limitadas retornam 429 rate_limit_error e podem incluir um header Retry-After.

On this page