API de cobrança

Traga o uso e o custo do seu próprio workspace para os seus próprios sistemas, sem abrir o console. Uma chave de cobrança é uma somente leitura credencial restrita a um único workspace - ela só pode ler dados de cobrança, nada mais.

Criar uma chave de cobrança

1. Abra Console → Chaves da API de cobrança (somente proprietário do workspace). Dê um nome a ela, opcionalmente restrinja-a a uma lista de permissões de IP ou defina uma expiração e, em seguida, copie a chave - ela começa com sk-syn-bill- e é exibida apenas uma vez.
2. Chame os endpoints abaixo usando-a como token Bearer. Revogue-a a qualquer momento na mesma página - revogar a invalida imediatamente e não afeta mais nada no workspace.
3. Uma chave está vinculada a quem a criou: se essa pessoa deixar de ser o proprietário do workspace, ela para de funcionar e retorna 403 key_owner_not_authorized.

Autenticação

Cada chamada precisa de Authorization: Bearer sk-syn-bill-... contra a URL base abaixo. Uma chave de cobrança só funciona nesses endpoints, e esses endpoints só aceitam uma chave de cobrança - qualquer outra combinação retorna 401 wrong_key_kind.

Authorization: Bearer sk-syn-bill-...

URL base: https://synthorai.io/api/v1/billing

GET /usage - uso agregado

GET /usage

Linhas pré-agregadas por hora ou por dia, feitas para faturamento e painéis. Vêm do agregado horário somado às requisições gravadas desde a última ingestão, então os buckets recentes não ficam um ciclo de ingestão inteiro atrasados.

Em cada linha, api_key_id e api_key_name só aparecem quando group_by inclui api_key, e model somente quando inclui model. avg_latency_ms pode ser null quando um bucket não tem amostras de latência.

Exemplo de requisição

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemplo de resposta

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - linhas por requisição

GET /records

Uma linha por requisição, pensada para a sincronização incremental no seu próprio banco de dados. Sincronize por cursor, nunca por tempo, e remova duplicatas das linhas recebidas por record_id - veja "Evitando lacunas de tempo" abaixo para saber por quê.

Exemplo de requisição

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemplo de resposta

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - exportação em streaming

GET /records/export

Os mesmos filtros de /records, transmitidos como JSON delimitado por novas linhas (application/x-ndjson) - feito para um grande backfill em vez de uma lista paginada. Apenas uma exportação pode ser transmitida por workspace por vez; uma segunda recebe 429 too_many_concurrent_requests.

Exemplo de requisição

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemplo de resposta

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

A última linha do stream é um _meta objeto:

GET /summary - estatísticas preliminares e anomalias

GET /summary

Totais, os principais modelos e chaves por custo, e uma taxa de erro para o intervalo, além de uma anomalies lista (high_error_rate, rate_limited, data_not_final, rollup_delayed), cada uma com uma gravidade info ou warning e uma mensagem legível. Os números de um intervalo não finalizado ainda podem mudar - veja abaixo.

models_count e keys_count fornecem os totais por trás de top_models e top_keys, que listam no máximo os 20 principais por custo. O intervalo padrão são os 30 dias antes de end quando start é omitido.

Exemplo de requisição

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemplo de resposta

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - grau de integridade dos dados

GET /freshness

Retorna data_complete_until, latest_recorded_at, safe_until e pipeline_lag_seconds - consulte-o antes de tratar um intervalo recém-obtido como definitivo. safe_until é o recorded_at mais recente que um chamador pode considerar completo; linhas mais recentes ainda podem estar chegando.

Exemplo de requisição

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemplo de resposta

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - o que o workspace pode gastar agora

GET /balance

Retorna o saldo disponível atual do workspace, o mesmo valor exibido no console. Feito para consultas periódicas: a cada 30 a 60 segundos é suficiente. Tem um limite de taxa próprio, então consultá-lo não consome o orçamento dos endpoints de dados, e ele responde mesmo com saldo zero.

Exemplo de requisição

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemplo de resposta

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

Erros

Cada erro é {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

Limites de taxa e limites máximos

Nunca é retornado: channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

Evitando lacunas de tempo

As requisições são gravadas no log de forma assíncrona após terminarem (normalmente segundos, mais tempo em caso de acúmulo), e o rollup por hora que /usage e /summary leem é ingerido em lotes. As horas mais recentes estão sempre um pouco incompletas. /usage e /summary também somam as requisições gravadas desde a última ingestão (meta.live_tail é true); se o agregado estiver atrasado demais para isso, meta.live_tail é false e os buckets recentes ficam parciais.

data_complete_until é o mais antigo entre estes dois pontos: a marca d'água do rollup por hora menos seu atraso de pipeline atual, ou a requisição mais antiga ainda não incorporada ao rollup - menos uma margem de segurança de 30 minutos, arredondada para baixo até a hora.

Cada linha de /usage carrega um indicador final : true , válido assim que seu bucket termina antes ou em data_complete_until (valor de /freshness). Um bucket final nunca muda novamente.

• Agregados: faça upsert de cada linha no seu próprio armazenamento por (bucket_start, api_key_id, model), e busque novamente qualquer bucket enquanto ele ainda for final: false. Nunca calcule um delta subtraindo um total antigo de um novo.
• Linhas brutas: sincronize por cursor, nunca por tempo. Guarde o next_cursor e retome a partir dele na próxima chamada, e remova duplicatas das linhas recebidas por record_id (um id opaco estável por linha) para o caso de uma página reenviada entregar a mesma linha de novo. Linhas com menos de cerca de 5 minutos são retidas - safe_until é o horário da linha mais recentemente registrada menos 5 minutos - de modo que uma linha ainda sendo confirmada nunca escape para antes de uma posição de cursor já entregue, e nada cai em uma lacuna. Para contar requisições, conte os request_id distintos.
• Janela delimitada: se você consultar um intervalo start/end em vez de sincronizar por cursor, confie que ele está completo somente quando window_final for true (só é true quando você informou um end e ele é anterior ou igual a safe_until). Se window_final for false, chame novamente depois com o mesmo intervalo, ou passe a sincronizar por cursor. Uma janela deve começar no máximo em safe_until; um início posterior retorna 400 start_too_recent com um cabeçalho Retry-After.

Integração recomendada

• Faturamento noturno: chame /usage uma vez por dia com granularity=day, e busque novamente qualquer bucket que sua última execução ainda via como final: false.
• Detalhe por requisição: chame /records a cada hora com cursor definido para o último next_cursor que você armazenou, continue paginando enquanto has_more for true, e remova duplicatas das linhas recebidas por record_id.
• Painéis: chame /summary para o intervalo visível em vez de agregar /records você mesmo - ele já traz a lista de anomalias.

Precisa gerar ou gerenciar chaves de API normais de forma programática em vez de ler dados de cobrança? Consulte Chaves de provisioning.