Retorna custos agregados por modelo (tokens, custo USD/BRL com IOF), custo médio por conversa (últimas 10, 24h, 7 dias, período), informações do plano do host e câmbio USD→BRL.

​
Endpoint

POST /api/externalAPIs/public/tolkyReasoning/reports/getCostByHostId

​
Autenticação

Bearer token no header Authorization, ou hostId no body para ambiente local.

​
Parâmetros

ParâmetroTipoObrigatórioDescrição
hostIdstring (UUID)Não*UUID do host. *Se não enviado, é extraído do Bearer token.
avatarIdstring (UUID)NãoUUID do avatar para filtrar (reservado para uso futuro).
startDatestring (date)NãoData inicial YYYY-MM-DD. Default: primeiro dia do mês atual.
endDatestring (date)NãoData final YYYY-MM-DD. Default: hoje (clampado para D-1).

​
Exemplo

curl -X POST \
  '{{BASE_URL}}/api/externalAPIs/public/tolkyReasoning/reports/getCostByHostId' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -d '{
    "startDate": "2026-03-01",
    "endDate": "2026-03-27"
  }'

​
Resposta

{
  "code": 200,
  "message": "OK",
  "data": {
    "costs": [
      {
        "model": "gpt-5.2-2025-12-11",
        "provider": "openai",
        "total_tokens": 190397394,
        "prompt_tokens": 184033664,
        "response_tokens": 6363730,
        "total_cost_usd": 411.155354,
        "total_cost_brl": 2226.94,
        "exchange_rate_usd_to_brl": 5.2331,
        "iof_rate": "3.5%"
      }
    ],
    "host_info": {
      "total_contracted_services": "10000",
      "service_pricing_contracted": 1.44
    },
    "currency_info": {
      "usd_to_brl_rate": 5.2331,
      "iof_rate": "3.5%",
      "last_updated": "2026-03-27T17:29:13.474Z"
    },
    "cost_per_conversation": {
      "last_10_conversations": {
        "average_cost_usd": 0.087747,
        "average_cost_brl": 0.46
      },
      "last_24h_conversations": {
        "average_cost_usd": 0.092338,
        "average_cost_brl": 0.48,
        "total_conversations": 254
      },
      "last_7days_conversations": {
        "average_cost_usd": 0.072314,
        "average_cost_brl": 0.38,
        "total_conversations": 985
      },
      "period_conversations": {
        "average_cost_usd": 0.108344,
        "average_cost_brl": 0.57,
        "total_conversations": 5642
      }
    },
    "filter_dates": {
      "requested_start_date": "2026-03-01",
      "requested_end_date": "2026-03-27",
      "applied_start_date": "2026-03-01",
      "applied_end_date": "2026-03-26",
      "was_clamped": true
    },
    "data_last_updated": "2026-03-26"
  }
}

​
Campos da Resposta

​
costs — Custos agregados por modelo

CampoTipoDescrição
modelstringNome do modelo LLM
providerstringProvedor do modelo (openai, google, etc)
total_tokensnumberTotal de tokens consumidos
prompt_tokensnumberTokens de entrada (prompt)
response_tokensnumberTokens de saída (resposta)
total_cost_usdnumberCusto total em USD
total_cost_brlnumberCusto total em BRL (com IOF)
exchange_rate_usd_to_brlnumberTaxa de câmbio USD→BRL utilizada
iof_ratestringTaxa de IOF aplicada na conversão

​
host_info — Informações do plano

CampoTipoDescrição
total_contracted_servicesstringQuantidade de serviços contratados
service_pricing_contractednumberPreço por serviço contratado (BRL)

​
currency_info — Informações de câmbio

CampoTipoDescrição
usd_to_brl_ratenumberTaxa de câmbio USD→BRL
iof_ratestringTaxa de IOF aplicada
last_updatedstringData/hora da última atualização

​
cost_per_conversation — Custo médio por conversa

Cada sub-objeto contém:

CampoTipoDescrição
average_cost_usdnumberCusto médio por conversa em USD
average_cost_brlnumberCusto médio por conversa em BRL
total_conversationsnumberTotal de conversas no período (exceto last_10)

Períodos disponíveis: last_10_conversations, last_24h_conversations, last_7days_conversations, period_conversations.

​
filter_dates — Datas aplicadas no filtro

CampoTipoDescrição
requested_start_datestringData inicial enviada na requisição
requested_end_datestringData final enviada na requisição
applied_start_datestringData inicial efetivamente utilizada
applied_end_datestringData final efetivamente utilizada (pode ser D-1)
was_clampedbooleantrue se a data final foi ajustada para D-1

​
data_last_updated — Última data processada

CampoTipoDescrição
data_last_updatedstring/nullÚltima data disponível nos dados enriquecidos

​
Erros

CódigoDescrição
400Campos obrigatórios ausentes ou inválidos
401Token inválido ou ausente
500Erro interno do servidor

​
Notas

  • Os custos são calculados a partir de tabelas pré-agregadas (cost_daily_summary e cost_conversation_summary), atualizadas diariamente às 3h.
  • A conversão USD→BRL utiliza a taxa de câmbio em tempo real da API open.er-api.com, com cache de 5 minutos.
  • O IOF de 3.5% é aplicado apenas na conversão para BRL. Os valores em USD são sem IOF.
  • O resultado completo é cacheado por 2 minutos para reduzir carga no banco.
  • Apenas conversas com pelo menos uma mensagem do usuário (role = 'user') são contabilizadas no custo médio por conversa.
Obter Estatísticas ConversacionaisObter Estatísticas Financeiras