Consumo de uma janela
Diz quanto foi consumido numa janela de dias, em que e por quem: o total de mensagens, tokens, chamadas e minutos, o custo repartido entre modelo e telefonia, a série dia a dia, e o detalhamento por modelo, por cliente, por operadora e por agente. Todo custo vem em milionésimos inteiros de dólar (*_usd_micros, moeda em currency): cada parcela é o custo calculado arredondado ao micro mais próximo, e todo total é a soma inteira das suas parcelas. O alcance é o de quem pergunta — a plataforma inteira, a carteira da revenda ou o próprio cliente —, e tenant_id/dealer_id apenas estreitam dentro dele: pedir um cliente fora do alcance responde 404 TENANT_NOT_FOUND, e uma revenda fora do alcance 404 DEALER_NOT_FOUND, como algo que não existe — nunca um relatório zerado. Com os dois, o cliente tem de ser daquela revenda; um cliente que nomeia a própria revenda continua vendo só o próprio consumo.
O custo é sempre calculado aqui, a partir do preço por modelo cadastrado; o cliente exibe estes valores e não os recalcula a partir dos tokens. Quando algum modelo usado não tem preço cadastrado, os tokens dele entram a zero: cost_source responde partial e unpriced_models diz quais são, para o total incompleto ser visível em vez de silencioso. Do mesmo jeito, uma operadora sem preço por minuto cadastrado cobra a telefonia a zero: cost_source responde partial e unpriced_telephony_providers a nomeia.
Autorização
bearer usage:readCredencial da v3: o JWT da sessão (o mesmo da v2) ou um token pessoal dom_pat_…. A lista de escopos de cada operação diz o que ela exige: uma capacidade (agents:read), authenticated ou session-only. Segredo de máquina (X-Agent-Secret, X-API-Token, sdk_…) não é aceito.
Em: header
Escopo: usage:read
Parâmetros de consulta
Primeiro dia da janela (AAAA-MM-DD, fuso de São Paulo). O padrão são
30 dias antes de end_date.
dateÚltimo dia da janela, incluído. O padrão é hoje.
dateEstreita para um cliente, dentro do alcance de quem pergunta.
int64Estreita para uma revenda: a plataforma escolhe qualquer uma, a revenda só a si mesma, e um cliente só a própria, sem sair do próprio cliente.
int64Corpo da resposta
application/json
application/json
curl -X GET "https://example.com/usage"{ "active_inboxes": 0, "active_tenants": 0, "by_agent": [ { "agent_id": "string", "agent_name": "string", "cost_usd_micros": 0, "text": { "messages": 0, "tenant_name": "string", "total_tokens": 0 }, "type": "text" } ], "by_date": [ { "cached_tokens": 0, "date": "string", "estimated_cost_usd_micros": 0, "input_tokens": 0, "output_tokens": 0, "session_tokens": 0, "total_messages": 0, "total_tokens": 0, "voice_calls": 0, "voice_cost_usd_micros": 0 } ], "by_model": [ { "avg_latency_ms": 0.1, "cached_cost_usd_micros": 0, "cached_tokens": 0, "cost_usd_micros": 0, "input_cost_usd_micros": 0, "input_tokens": 0, "model": "string", "output_cost_usd_micros": 0, "output_tokens": 0, "priced": true, "total_tokens": 0, "usage_count": 0 } ], "by_telephony_provider": [ { "calls": 0, "cost_usd_micros": 0, "minutes_billed": 0.1, "model_cost_usd_micros": 0, "telephony_cost_usd_micros": 0, "telephony_provider": "string" } ], "by_tenant": [ { "cost_usd_micros": 0, "tenant_id": 0, "tenant_name": "string", "total_messages": 0, "total_tokens": 0 } ], "by_voice_model": [ { "calls": 0, "cost_usd_micros": 0, "minutes_billed": 0.1, "model": "string", "model_cost_usd_micros": 0, "studio_minutes": 0.1, "studio_model_cost_usd_micros": 0, "studio_sessions": 0, "telephony_cost_usd_micros": 0, "total_tokens": 0 } ], "cost_source": "backend", "currency": "string", "period": { "days": 0, "end_date": "string", "start_date": "string" }, "summary": { "avg_latency_ms": 0.1, "avg_tokens_per_message": 0.1, "cost_breakdown": { "cached_usd_micros": 0, "input_usd_micros": 0, "output_usd_micros": 0, "total_usd_micros": 0 }, "estimated_cost_usd_micros": 0, "grand_total_cost_usd_micros": 0, "studio": { "text": { "cost_usd_micros": 0, "messages": 0, "total_tokens": 0 }, "total_cost_usd_micros": 0, "voice": { "minutes": 0.1, "model_cost_usd_micros": 0, "sessions": 0, "total_tokens": 0 } }, "total_conversations": 0, "total_messages": 0, "total_tokens": { "cached": 0, "input": 0, "output": 0, "pure_input": 0, "session": 0, "total": 0 }, "voice_calls_count": 0, "voice_cost_breakdown": { "model_minutes_usd_micros": 0, "model_usd_micros": 0, "studio_model_usd_micros": 0, "telephony_usd_micros": 0, "total_usd_micros": 0 }, "voice_minutes_billed": 0.1, "voice_minutes_total": 0.1 }, "total_inboxes": 0, "total_tenants": 0, "unpriced_models": [ "string" ], "unpriced_telephony_providers": [ "string" ]}