Reporting API

Consulte URLs e autenticação HTTP 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.

A Reporting API está obsoleta. As chamadas existentes para POST /v2/reporting continuam funcionando, mas novas integrações devem usar a Telemetry API, 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 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.

Dashboards de gastos

Acompanhe o custo por modelo, provedor, projeto ou tipo de credencial. Crie detalhamentos de faturamento por cliente.

Monitoramento de desempenho

Monitore a latência p50, p95 e p99 ao longo do tempo entre modelos e provedores.

Qualidade dos evaluators

Quantifique a taxa de aprovação, a pontuação média e a distribuição de resultados por Evaluator e versão.

Aplicação de guardrails

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.

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.

Consulte a Referência da API

Playground interativo e esquema completo de POST /v2/reporting.

Solicitação

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).

{
  "metric": "genai.usage",
  "from": "<ISO-8601 start datetime>",
  "to":  "<ISO-8601 end datetime>",
  "grain": "day",
  "group_by": ["model", "provider"],
  "filters": [
    { "field": "project", "op": "eq", "values": ["proj_123"] }
  ],
  "include_totals": true,
  "limit": 1000,
  "time_zone": "UTC"
}

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.

Consulte a referência da API 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)
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.

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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

Uso
Evaluator
Guardrail

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

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.

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

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

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.

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.

Dimensões de uso
Dimensões de entidade
Dimensões de evaluator e guardrail

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.

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

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.

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.

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.

{
  "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.

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

Acompanhamento de tokens e custos

Como o uso de tokens é capturado e o custo é calculado para cada solicitação de LLM.

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Dashboards de gastos

Monitoramento de desempenho

Qualidade dos evaluators

Aplicação de guardrails

Endpoint

Consulte a Referência da API

Solicitação

Resposta

Catálogo de métricas

Dimensões

Erros

Limites

Acompanhamento de tokens e custos

Dashboards de gastos

Monitoramento de desempenho

Qualidade dos evaluators

Aplicação de guardrails

​Endpoint

Consulte a Referência da API

​Solicitação

​Resposta

​Catálogo de métricas

​Dimensões

​Erros

​Limites

Acompanhamento de tokens e custos

Endpoint

Solicitação

Resposta

Catálogo de métricas

Dimensões

Erros

Limites