Uso e faturamento

A cobrança é por tentativa: cada item pedido conta, inclusive quando não tem buybox. A API devolve e armazena contagem - o preço unitário está no seu contrato, e a fatura aplica. Aqui está como conferir tudo antes de a fatura chegar.

O modelo, em três regras

• Um item é uma tentativa, no GET unitário ou dentro do lote. A forma da URL não é termo comercial.
• FOUND e EMPTY cobram; ERROR (falha nossa) e 503 nunca cobram. Marketplace desconhecido (404) não tenta nada e não cobra nada.
• Referência repetida no mesmo request é deduplicada e cobra 1. Requests separados são tentativas separadas.

O seu medidor

O medidor é da chave, não de um marketplace - por isso fica fora de /v1/{marketplace}. A fatura soma tudo que a chave consumiu, em qualquer marketplace, e este endpoint usa exatamente as mesmas fronteiras de mês que ela.

curl "https://api.geth.app/v1/usage?month=2026-07" \
  -H "Authorization: Bearer gk_live_SEU_TOKEN"

{
  "api_key": "gk_live_ab12cd34",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "attempts": 148230,
  "billable": 148230,
  "found": 51120,
  "empty": 97110,
  "error": 0,
  "by_day": [
    { "day": "2026-07-01", "attempts": 4980, "billable": 4980, "found": 1700, "empty": 3280, "error": 0 }
  ]
}

api_key é o prefixo público da chave (nunca o segredo). Só contagem: nenhum valor em reais aparece aqui.

Reconciliação linha a linha

Cada resposta de leitura traz o que você precisa para fechar a conta do seu lado, sem depender de relatório nosso:

• request_id - agrupa as tentativas daquela chamada no nosso registro. É a chave para abrir qualquer dúvida de cobrança com a gente.
• attempted / billable - as tentativas da chamada e o que entra na fatura.
• billable por item - diz se aquele item específico cobrou.

Boas práticas de consumo

• Sortimento inteiro = lote. O GET unitário é para consulta pontual; os dois custam igual por item, mas 200 GETs gastam 200x mais do seu rate limit do que um lote de 200.
• Paralelize lotes respeitando o rate limit da sua chave.
• Em 429, respeite o Retry-After; em 503, repita a chamada - nada foi cobrado.