Skip to main content
Este evento é publicado sempre que um custo baseado em uso é registrado para uma organização. Ele é o ponto de entrada do pipeline de faturamento — cada evento cost.requested representa uma unidade individual de consumo (ex.: chamadas de API, tokens de IA, mensagens enviadas) que precisa ser rastreada e eventualmente liquidada. O evento é disparado imediatamente quando o registro de custo é criado, antes de qualquer agregação em lote ou reporte ao billing meter. Consumidores downstream podem usar este evento para atualizar dashboards de uso em tempo real, aplicar limites de gastos ou disparar alertas.
Registros de custo são criados com um costBatchWindowRef que agrupa custos relacionados para liquidação em lote. O costBatchId será null até que o Processador de Liquidação de Custos agregue e liquide o lote.
Ao tratar este evento, use o costId como sua chave de idempotência. Se precisar correlacionar custos com o status de liquidação depois, armazene o costBatchWindowRef — ele vincula custos individuais ao seu eventual lote.

​
Detalhes do Evento

PropriedadeValor
Typecost.requested

​
Schema do Payload

​
costId
string (UUID v7)
required
Identificador único do registro de custo.
​
organizationId
string (UUID v7)
required
FK para Organization.
​
feeId
string (UUID v7)
required
FK para Fee.
​
tokenId
string (UUID v7)
required
FK para Token.
​
costBatchId
string (UUID v7)
FK para CostBatch.
​
costBatchWindowRef
string
required
Referência única da janela para agrupamento em lote.
​
quantity
integer
required
Unidades consumidas.
​
unitAmount
decimal
required
Preço por unidade.
​
unitAmountCurrency
string
required
Moeda do token (USD, BRL, EUR).
​
subtotalAmount
decimal
required
quantity x unitAmount.
​
exchangeRate
decimal
required
Taxa de conversão aplicada.
​
exchangeRateProvider
string
required
Provedor da taxa de câmbio.
​
totalAmount
decimal
required
Valor final na moeda da organização.
​
totalAmountCurrency
string
required
Moeda da organização (USD, BRL, EUR).
​
createdAt
string (ISO 8601)
required
Timestamp de criação.
​
updatedAt
string (ISO 8601)
required
Timestamp da última atualização.
{
  "specversion": "1.0",
  "type": "cost.requested",
  "id": "evt_0195f3a2-8c00-7d4e-b808-8b9c0d1e2f3a",
  "time": "2026-03-25T14:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "costId": "0195f3a2-8c00-7d4e-b808-8b9c0d1e2f3a",
    "organizationId": "0195f3a2-8c00-7d4e-b801-1a2b3c4d5e6f",
    "feeId": "0195f3a2-7b8c-7d9e-a0b1-c2d3e4f56789",
    "tokenId": "0195f3a2-8c00-7d4e-b807-7a8b9c0d1e2f",
    "costBatchId": null,
    "costBatchWindowRef": "a1b2c3d4e5f6",
    "quantity": 150,
    "unitAmount": 5.90,
    "unitAmountCurrency": "USD",
    "subtotalAmount": 885.00,
    "exchangeRate": 1.0,
    "exchangeRateProvider": "ecb",
    "totalAmount": 885.00,
    "totalAmountCurrency": "BRL",
    "createdAt": "2026-03-25T14:00:00Z",
    "updatedAt": "2026-03-25T14:00:00Z"
  }
}