> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Reporting API > Use a Reporting API do Toqan Router para acessar de forma programática análises de uso, custo, latência, tokens, evaluators e guardrails de IA, detalhadas por qualquer dimensão. Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) e a referência da API para os formatos completos de solicitação e resposta. Consulte de forma programática o uso de IA, custo, latência, resultados de Evaluators e métricas de guardrails. A **Reporting API** retorna dados de séries temporais divididos por modelo, provedor, projeto, identidade e mais, em uma única solicitação JSON. > [!WARNING] > > A **Reporting API** está obsoleta. As chamadas existentes para `POST /v2/reporting` continuam funcionando, mas novas integrações devem usar a [Telemetry API](/docs/pt-BR/ai-studio/observability/telemetry-api.md), e as existentes devem migrar para ela. > > Para migrar uma solicitação: > > * Envie-a para `POST /v3/telemetry/query` com `"source": "TELEMETRY_SOURCE_TRACES"`. > * Substitua `"metric": "genai.cost"` por `"compute": [{ "metric": "genai.cost", "op": "sum" }]`. Os nomes de métricas `genai.*` são mantidos; consulte [Fontes e métricas](/docs/pt-BR/ai-studio/observability/telemetry-api.md#sources-and-metrics) para ver as operações de cada métrica. Para `genai.usage`, use `"op": "bundle"`. > * Leia `group` em vez de `dimensions` em cada linha. As chaves de métricas são a métrica e a operação unidas por dois-pontos, por exemplo `genai.cost:sum`. > [card] [Dashboards de gastos](#metric-catalog) > > Acompanhe o custo por modelo, provedor, projeto ou tipo de credencial. Crie detalhamentos de faturamento por cliente. > [card] [Monitoramento de desempenho](#metric-catalog) > > Monitore a latência p50, p95 e p99 ao longo do tempo entre modelos e provedores. > [card] [Qualidade dos evaluators](#metric-catalog) > > Quantifique a taxa de aprovação, a pontuação média e a distribuição de resultados por **Evaluator** e versão. > [card] [Aplicação de guardrails](#metric-catalog) > > Meça a taxa de bloqueio, os acionamentos e os resultados por **Policy** e estágio. ## Endpoint POST `https://router.toqan.ai/eu/v2/reporting` * Todas as solicitações exigem um token `Bearer`. Consulte API Keys para saber como gerar um. * O escopo de workspace e de projeto é derivado da própria chave de API. > [!NOTE] > > Os eventos de trace chegam ao reporting quase em tempo real, com um pequeno atraso de ingestão medido em segundos. Consultas em janelas muito recentes podem ainda não incluir os eventos mais recentes. > [card] [Consulte a Referência da API](/docs/pt-BR/reference/reporting/query-reporting-metrics.md) > > Playground interativo e esquema completo de `POST /v2/reporting`. ## Solicitação > [!NOTE] > > O formato enviado é **snake\_case** de ponta a ponta. Os SDKs expõem os mesmos campos no estilo nativo de cada linguagem (`groupBy` em **TypeScript**, `group_by` em **Python**). ```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}} { "metric": "genai.usage", "from": "", "to": "", "grain": "day", "group_by": ["model", "provider"], "filters": [ { "field": "project", "op": "eq", "values": ["proj_123"] } ], "include_totals": true, "limit": 1000, "time_zone": "UTC" } ``` ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} FROM=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "1 day ago" +%Y-%m-%dT%H:%M:%SZ) TO=$(date -u +%Y-%m-%dT%H:%M:%SZ) curl -X POST "https://router.toqan.ai/eu/v2/reporting" \ -H "Authorization: Bearer $TOQAN_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"metric\": \"genai.usage\",\"from\": \"$FROM\",\"to\": \"$TO\",\"grain\": \"day\",\"group_by\": [\"model\", \"provider\"],\"filters\": [{ \"field\": \"project\", \"op\": \"eq\", \"values\": [\"proj_123\"] }],\"include_totals\": true,\"limit\": 1000,\"time_zone\": \"UTC\"}" ``` `grain` define o bucket de tempo: `auto`, `minute`, `hour` ou `day`. Com `auto`, ou com o campo omitido, o servidor escolhe o bucket. A resposta informa o bucket aplicado em `meta.effective_grain`. > [!NOTE] > > Consulte a [referência da API](/docs/pt-BR/reference/reporting/query-reporting-metrics.md) para ver o esquema completo dos campos, tipos, valores padrão e regras de validação. **Formatação dos valores com `mode`**: o modo padrão `timeseries` retorna uma linha por bucket de tempo. Defina `"mode": "scalar"` para agregar toda a janela: com `group_by`, a resposta traz uma linha por combinação de dimensões, ordenada por valor (uma top list, limitada por `limit`; inverta a ordem com `"sort": "asc"`), e sem `group_by`, exatamente uma linha (um único agregado). As linhas scalar omitem o campo `timestamp`. ## Resposta Toda resposta bem-sucedida segue o mesmo envelope. O array `data` contém buckets ordenados no tempo. Cada bucket contém: * um mapa `dimensions`: os valores de `group_by` daquela linha (consulte [Dimensões](#dimensions)) * um mapa `metrics`: o formato depende da métrica solicitada **Métricas escalares** retornam um único valor nomeado por bucket. **Métricas em pacote** (como `genai.usage`) retornam um conjunto completo de campos relacionados em uma única chamada. `totals` só está presente quando `include_totals: true` é definido na solicitação; caso contrário, o campo é omitido. Os valores das métricas são arredondados para 10 casas decimais no servidor. ```json Response envelope (with totals) theme={"theme":{"light":"github-light","dark":"github-dark"}} { "object": "report", "request": { }, "data": [ { "timestamp": "2026-05-01T00:00:00Z", "dimensions": { "model": "openai/gpt-5.4-mini", "provider": "openai" }, "metrics": { } } ], "totals": { "metrics": { } }, "has_more": false, "meta": { "effective_grain": "day", "row_count": 14, "request_id": "req_...", "currency": "USD" } } ``` ```json Scalar metric theme={"theme":{"light":"github-light","dark":"github-dark"}} { "object": "report", "request": { "metric": "genai.cost", "from": "2026-05-14T00:00:00Z", "to": "2026-05-16T00:00:00Z", "grain": "day", "group_by": ["model"], "include_totals": false, "mode": "timeseries", "sort": "desc" }, "data": [ { "timestamp": "2026-05-14T00:00:00Z", "dimensions": { "model": "openai/gpt-5.4-mini" }, "metrics": { "genai.cost": 0.000225 } } ], "has_more": false, "meta": { "effective_grain": "day", "row_count": 1, "request_id": "req_...", "currency": "USD" } } ``` ```json Bundle metric (genai.usage) theme={"theme":{"light":"github-light","dark":"github-dark"}} { "object": "report", "request": { "metric": "genai.usage", "from": "2026-05-14T00:00:00Z", "to": "2026-05-15T00:00:00Z", "grain": "day", "group_by": ["model"], "include_totals": false, "mode": "timeseries", "sort": "desc" }, "data": [ { "timestamp": "2026-05-14T00:00:00Z", "dimensions": { "model": "openai/gpt-5.4-mini" }, "metrics": { "request_count": 44, "error_count": 0, "input_tokens": 660, "output_tokens": 660, "total_tokens": 1320, "cached_input_tokens": 0, "reasoning_tokens": 0, "audio_input_tokens": 0, "audio_output_tokens": 0, "total_cost": 0.000495, "input_cost": 0.000099, "output_cost": 0.000396, "cached_cost": 0, "reasoning_cost": 0 } } ], "has_more": false, "meta": { "effective_grain": "day", "row_count": 1, "request_id": "req_...", "currency": "USD" } } ``` ## Catálogo de métricas > [tab] Uso > > | Métrica | Descrição | > | - | - | > | `genai.requests` | Número de solicitações de LLM | > | `genai.tokens` | Total de tokens (entrada + saída) | > | `genai.cost` | Custo total em USD | > | `genai.errors` | Número de solicitações com falha | > | `genai.error_rate` | Solicitações com falha / total (proporção em `[0, 1]`) | > | `genai.latency.p50` | Latência mediana das solicitações (ms) | > | `genai.latency.p95` | Latência no percentil 95 (ms) | > | `genai.latency.p99` | Latência no percentil 99 (ms) | > | `genai.ttft.avg` | Tempo médio até o primeiro token (ms, somente streaming) | > | `genai.ttft.p50` | Tempo mediano até o primeiro token (ms, somente streaming) | > | `genai.ttft.p95` | Tempo até o primeiro token no percentil 95 (ms, somente streaming) | > | `genai.usage` | Pacote de campos de solicitações, tokens e custo | > > > [!NOTE] > > > > As métricas de quantil (`genai.latency.p*`, `genai.ttft.p*`) têm uma margem de > > erro de +/-1-2%, típica da estimativa por t-digest em alta cardinalidade. As > > métricas `genai.ttft.*` abrangem somente solicitações com streaming e não > > aceitam dimensões de entidade como `agent` ou `tool`. > [tab] Evaluator > > | Métrica | Descrição | > | - | - | > | `genai.evaluator.runs` | Total de execuções de **Evaluator** | > | `genai.evaluator.pass_rate` | Aprovados / total (proporção em `[0, 1]`) | > | `genai.evaluator.score.avg` | Pontuação média do **Evaluator** | > [tab] Guardrail > > | Métrica | Descrição | > | - | - | > | `genai.guardrail.runs` | Total de verificações de guardrail | > | `genai.guardrail.block_rate` | Bloqueados / total (proporção em `[0, 1]`) | > | `genai.guardrail.triggered` | Contagem de verificações bloqueadas | > [!NOTE] > > As métricas de Evaluator e de guardrail são lidas da mesma fonte: toda execução de > **Evaluator** é registrada como uma verificação de guardrail, independentemente do tipo de implementação > do **Evaluator**. Escolha a métrica que corresponde à pergunta que está sendo feita. ## Dimensões As dimensões de entidade (`agent`, `tool` e assim por diante) estão disponíveis para métricas de uso e detalham uma métrica por uma entidade do produto. > [!NOTE] > > `billing_billable` está disponível como campo de filtro para métricas de uso, mas não > como dimensão de `group_by`. Para separar credenciais gerenciadas pelo **Toqan Router** das credenciais do cliente, use `credential_type`. Os valores `orq_managed` e `customer_byok` são derivados no momento da consulta a partir da configuração de faturamento do workspace, e não armazenados em cada evento. > [tab] Dimensões de uso > > Combine-as com `genai.requests`, `genai.tokens`, `genai.cost`, `genai.errors`, `genai.latency.*` ou `genai.usage`. > > | Dimensão | Observações | > | - | - | > | `project` | Projeto do workspace ao qual a solicitação é atribuída | > | `identity` | Identificador do usuário final em **Identities** | > | `provider` | Por exemplo, `openai`, `anthropic` | > | `model` | Por exemplo, `gpt-5.4-mini` | > | `product` | Qual superfície de produto do **Toqan Router** atendeu à solicitação | > | `api_key` | Chave de API usada para autenticar a solicitação | > | `status_code` | Status de alto nível (`OK`, `ERROR`) | > | `http_status_code` | Status HTTP do modelo upstream | > | `credential_type` | `orq_managed` (chaves gerenciadas pelo **Toqan Router**) ou `customer_byok` (chaves BYOK do cliente) | > > Os valores de `status_code` correspondem às grafias da OQL e da Telemetry API em [Valores de status de trace](/docs/pt-BR/ai-studio/observability/telemetry-api.md#trace-status-values). > [tab] Dimensões de entidade > > Adicione uma dimensão de entidade a qualquer métrica de uso para detalhá-la por uma entidade do produto. > > | Entidade | Descrição | > | - | - | > | `agent` | **Agent** que emitiu a solicitação | > | `tool` | **Tool** invocada durante a solicitação | > | `deployment` | ID do **Deployment** | > | `evaluator` | **Evaluator** executado no trace | > | `policy` | **Policy** que correspondeu à solicitação | > | `prompt` | Modelo de **Prompt** | > | `dataset` | **Dataset** usado em um experimento | > | `conversation` | Agrupamento por conversa | > | `thread` | Agrupamento por **Thread** | > | `memory_store` | **Memory Store** | > | `knowledge` | Base de **Knowledge** | > > > [!TIP] > > > > Duas dimensões de entidade conflitantes na mesma solicitação (por exemplo, `["agent", > > "tool"]`) retornam `400`. Faça uma solicitação por dimensão de entidade. > > > [!TIP] > > > > As consultas também podem agrupar por uma `dimension` bruta, mas precisam incluir um > > filtro `dimension_type`, como `{ "field": "dimension_type", "op": "eq", > > "values": ["agent"] }`. Prefira os aliases de entidade acima na maioria dos dashboards. > [tab] Dimensões de evaluator e guardrail > > Combine-as com as métricas `genai.evaluator.*` e `genai.guardrail.*`. > > | Dimensão | Observações | > | - | - | > | `project` | Projeto do workspace ao qual a solicitação é atribuída | > | `identity` | Identificador do usuário final em **Identities** | > | `api_key` | Chave de API usada para autenticar a solicitação | > | `policy` | **Policy** que correspondeu à solicitação | > | `evaluator` | **Evaluator** que produziu o resultado | > | `evaluator_name` | Nome legível do **Evaluator** | > | `evaluator_type` | `llm_eval`, `python_eval`, `function_eval` e assim por diante | > | `evaluator_version` | Compare versões ao longo do tempo | > | `result_type` | `boolean`, `number`, `categorical`, `string` | > | `result_label` | Bucket de resultado limitado (`pass`, `fail`, `error` ou nome da categoria) | > | `evaluation_stage` | `input` ou `output` (aliases: `guardrail_stage`, `evaluator_stage`) | > | `guardrail_action` | `block` ou outro | > | `guardrail_origin` | `rule` ou `direct` | > | `product` | Qual superfície de produto do **Toqan Router** atendeu à solicitação | > | `status_code` | Status de alto nível (`OK`, `ERROR`) | ## Erros Os erros são retornados como envelopes JSON com um `code` numérico, uma `message` legível e um array `details` vazio. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "code": 3, "message": "time range exceeds maximum: 11952h0m0s > 90d", "details": [] } ``` | HTTP | Código | Motivo | | - | - | - | | 400 | 3 | Métrica desconhecida, dimensão não permitida, intervalo fora da retenção do workspace, intervalo acima de 90 dias, `from >= to`, grain fora da retenção ou operador de filtro inválido. | | 401 | 16 | Token bearer ausente ou inválido. | | 403 | 7 | A chave de API não tem acesso ao projeto solicitado. | | 500 | 13 | Falha inesperada no backend. Encaminhe o `meta.request_id` ao suporte. | > [!TIP] > > Toda resposta bem-sucedida inclui `meta.request_id`. Inclua-o nos chamados de > suporte para uma correlação rápida dos logs. ## Limites | Limite | Valor | | - | - | | Janela de consulta | Período de retenção do workspace, limitado a 90 dias | | `group_by` | 5 colunas | | `filters` | 20 entradas | | `filter.values` | 100 valores por filtro | | `limit` | 5000 linhas de bucket (padrão 1000) | | Timeout por consulta | 30 segundos | > [card] [Acompanhamento de tokens e custos](/docs/pt-BR/ai-studio/observability/token-cost-tracking.md) > > Como o uso de tokens é capturado e o custo é calculado para cada solicitação de LLM. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.