Telemetry API

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta. A Telemetry API responde a perguntas sobre uso, custo, latência, traces e logs a partir de um único endpoint. Toda solicitação informa uma source, um intervalo de tempo e uma ou mais entradas compute, e todas as fontes respondem com o mesmo formato de linha.

A Telemetry API é a superfície de consulta recomendada para novas integrações: um único envelope abrange métricas de uso, agregados de traces e logs. A Reporting API está obsoleta em favor dela. Os endpoints de agregados de traces continuam com suporte para os chamadores existentes.

Uso e custo

Agrupe métricas genai por modelo, provedor, projeto, agent ou tool.

Agregados de traces

Conte traces e spans e obtenha percentis de latência ou totais de tokens e custo.

Volume de logs

Conte registros de log e registros de erro, agrupados por severidade ou serviço.

Descubra a superfície

Liste as métricas, operações e dimensões que o chamador pode acessar.

Endpoint

POST https://router.toqan.ai/eu/v3/telemetry/query

Todas as solicitações exigem um token Bearer. Consulte API Keys para saber como gerar um.
O escopo de workspace e projeto vem da chave de API.

Consultar telemetria

Esquema completo de POST /v3/telemetry/query.

Listar capacidades

GET /v3/telemetry/capabilities.

Listar valores de facetas

POST /v3/telemetry/facet-values.

Início rápido

Conte as solicitações por modelo no último dia:

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\",\"from\": \"$FROM\",\"to\": \"$TO\",\"compute\": [{\"metric\": \"genai.requests\", \"op\": \"count\"}],\"grain\": \"hour\",\"group_by\": [\"model\"]}"

Solicitação

Campo	Tipo	Descrição
`source`	string	`TELEMETRY_SOURCE_TRACES`, `TELEMETRY_SOURCE_METRICS` ou `TELEMETRY_SOURCE_LOGS`. Obrigatório.
`compute`	array	De uma a dez entradas `{ "metric": "…", "op": "…" }`. Obrigatório.
`from`, `to`	timestamp	Limites RFC 3339. `from` é inclusivo e `to` é exclusivo nas fontes de traces e logs; a fonte de métricas inclui um ponto de dados registrado exatamente em `to`. Obrigatório.
`grain`	string	`none`, `auto`, `minute`, `hour` ou `day`. `none` e um campo omitido retornam uma linha por grupo em vez de uma série temporal.
`interval_seconds`	integer	Largura explícita do bucket, de 1 a 86400, com precedência sobre `grain`. Compatível com métricas brutas de traces, métricas de spans e a fonte de métricas. Rejeitado para métricas genai, que usam `grain`, e ignorado na fonte de logs.
`mode`	string	`timeseries` agrupa em buckets pelo grain; `scalar` retorna uma linha por grupo. Se omitido, o grain define o formato. Uma consulta genai escalar agrupada aceita exatamente uma entrada `compute`.
`group_by`	array	Até cinco dimensões para detalhar as linhas.
`filters`	array	Até vinte entradas `{ "field": "…", "op": "…", "values": ["…"] }`.
`filter_operator`	string	`and` ou `or` entre os filtros. O padrão é `and`.
`query`	string	Pesquisa de texto livre, com até 512 caracteres, correspondida como na pesquisa da lista de traces: IDs de trace, sessão e thread, além de nomes de spans, IDs de spans, modelos, provedores, nomes de agents e nomes de tools. Somente na fonte de traces com métricas brutas de traces; rejeitado para métricas genai e outras fontes.
`oql`	string	Seleção de traces em OQL (`fetch traces \| …`), com até 4096 caracteres, compilada em filtros. Somente na fonte de traces com métricas brutas de traces. Não pode ser combinado com `filters` ou `query`.
`sort`	string	`desc` ou `asc` para linhas escalares e de top list. O padrão é `desc`.
`limit`	integer	Consultas escalares: máximo de linhas, padrão 100. Consultas de séries temporais: máximo de grupos distintos; excedê-lo faz a consulta falhar em vez de truncar as linhas do tempo.
`time_zone`	string	Posiciona os limites dos buckets no fuso para métricas genai e de spans. Todas as outras fontes agrupam em UTC e retornam uma entrada em `meta.warnings` quando um fuso diferente de `UTC` é enviado.
`include_totals`	boolean	Adiciona uma linha `totals` que abrange toda a janela.
`selected_range_seconds`	integer	O intervalo que o cliente selecionou originalmente, para que `grain: "auto"` permaneça estável enquanto uma janela ao vivo cresce. Lido apenas por métricas brutas de traces e métricas de spans; todas as outras fontes determinam o bucket apenas a partir de `from` e `to`.

auto determina a largura do bucket a partir do intervalo solicitado, e a escala depende da fonte:

Fonte	Escala do `auto`
traces, métricas brutas de traces	1s até 5 minutos, 5s até 15 minutos, 15s até 30 minutos, 30s até uma hora, depois minute, 5m, 10m, 2h, 6h, 12h e day
traces, métricas genai	`minute` até 6 horas, `hour` até 7 dias, `day` acima disso
métricas	`minute` até 48 horas, `hour` até 14 dias, `day` acima disso
logs	`minute` até 6 horas, `hour` até 7 dias, `day` acima disso

Resposta

Todas as fontes respondem com o mesmo envelope:

Envelope

{
  "object": "telemetry.query",
  "request": { },
  "data": [
    {
      "timestamp": "2026-05-01T00:00:00Z",
      "group": { "model": "openai/gpt-5.4-mini" },
      "metrics": { "trace_count:count": 128 }
    }
  ],
  "totals": {
    "group": { },
    "metrics": { "trace_count:count": 4021 }
  },
  "meta": {
    "effective_grain": "hour",
    "warnings": [],
    "row_count": 24,
    "request_id": "req_...",
    "currency": ""
  },
  "has_more": false
}

As chaves de metrics são a métrica e a operação solicitadas unidas por dois-pontos, por exemplo trace_count:count ou genai.cost:sum.
timestamp está presente apenas em linhas agrupadas em buckets.
totals aparece apenas quando a solicitação define include_totals: true e não traz timestamp, com um group vazio.
meta.effective_grain informa o bucket efetivamente aplicado, incluindo as larguras às quais interval_seconds ou auto foram resolvidos. meta.currency é USD somente quando todas as entradas compute são genai.cost, e fica vazio em qualquer outra consulta.
meta.warnings explica um valor que a fonte ignorou, por exemplo um time_zone enviado a uma fonte que agrupa em UTC.

Fontes e métricas

TELEMETRY_SOURCE_TRACES abrange agregados brutos de traces, as métricas de uso genai e as métricas de spans. Os três não podem ser misturados em uma única solicitação. As métricas de spans (gen_ai.* e orq.gen_ai.*) são calculadas por span de solicitação de LLM. Elas respeitam time_zone e aceitam vários computes em uma consulta escalar agrupada, ordenada pelo primeiro.

Métrica	Operações	Fonte
`trace_count`	`count`	traces
`span_count`	`count`	traces
`duration_ms`	`avg`, `p50`, `p95`, `p99`, `min`, `max`	traces
`tokens.total`, `tokens.prompt`, `tokens.completion`	`sum`, `avg` no total; `sum` nos detalhamentos	traces
`cost.total`, `cost.input`, `cost.output`	`sum`, `avg` no total; `sum` nos detalhamentos	traces
`error_count`	`count`	traces
`error_rate`	`ratio`	traces
`genai.requests`	`count`	traces
`genai.tokens`	`sum`	traces
`genai.cost`	`sum`	traces
`genai.errors`	`count`	traces
`genai.error_rate`	`rate`	traces
`genai.latency.avg`	`avg`	traces
`genai.latency.p50`, `genai.latency.p90`, `genai.latency.p95`, `genai.latency.p99`	`p50`, `p90`, `p95`, `p99`, um por métrica	traces
`genai.ttft.runs`	`count`	traces
`genai.ttft.avg`	`avg`	traces
`genai.ttft.p50`, `genai.ttft.p90`, `genai.ttft.p95`, `genai.ttft.p99`	`p50`, `p90`, `p95`, `p99`, um por métrica	traces
`genai.tokens.input`, `genai.tokens.output`, `genai.tokens.cached`, `genai.tokens.reasoning`	`sum`	traces
`genai.cost.input`, `genai.cost.output`, `genai.cost.cache_read`, `genai.cost.cache_write`, `genai.cost.web_search`	`sum`	traces
`genai.cache_hit_rate`	`rate`	traces
`genai.blended_cost_per_mtok`	`avg`	traces
`genai.evaluator.runs`, `genai.evaluator.errors`, `genai.guardrail.runs`, `genai.guardrail.triggered`	`count`	traces
`genai.evaluator.pass_rate`, `genai.evaluator.fail_rate`, `genai.evaluator.error_rate`, `genai.guardrail.block_rate`	`rate`	traces
`genai.evaluator.score.avg`	`avg`	traces
`gen_ai.client.inference.duration`, `gen_ai.client.inference.time_to_first_chunk`, `gen_ai.server.time_per_output_token`, `orq.gen_ai.generation.duration` (segundos), `orq.gen_ai.output_throughput` (tokens por segundo)	`avg`, `p50`, `p90`, `p95`, `p99`, `min`, `max`	traces
`orq.gen_ai.requests`, `orq.gen_ai.errors`, `orq.gen_ai.response_cache.hits`	`count`	traces
`orq.gen_ai.error_rate`, `orq.gen_ai.cache_hit_rate`, `orq.gen_ai.blended_cost_per_mtok`, `orq.gen_ai.response_cache.hit_rate`	`ratio`	traces
`gen_ai.client.inference.usage.input_tokens`, `gen_ai.client.inference.usage.output_tokens`, `gen_ai.client.inference.usage.reasoning.output_tokens`, `gen_ai.client.inference.usage.cache_read.input_tokens`, `gen_ai.client.inference.usage.cache_write.input_tokens`, `orq.gen_ai.usage.total_tokens`	`sum`, `avg`, `p50`, `p90`, `p95`, `p99`	traces
`orq.gen_ai.cost`, `orq.gen_ai.cost.input`, `orq.gen_ai.cost.output`, `orq.gen_ai.cost.cache_read`, `orq.gen_ai.cost.cache_write`, `orq.gen_ai.cost.reasoning`, `orq.gen_ai.cost.web_search`	`sum`, `avg`	traces
`log_count`	`count`	logs
`error_count`, `error_rate`	`count`, `ratio`	logs

TELEMETRY_SOURCE_METRICS abrange as métricas personalizadas registradas no workspace. TELEMETRY_SOURCE_LOGS abrange apenas registros de log. genai.usage é um pacote: solicite-o com op: "bundle" e ele retorna todos os campos em uma única linha, sob chaves genai.usage:<field>. Seus campos não são métricas consultáveis isoladamente, e esse compute não pode ser combinado com nenhum outro na mesma solicitação.

Descubra o que está disponível

As capacidades listam o que uma chave pode acessar, para que o cliente nunca precise fixar o vocabulário no código:

curl "https://router.toqan.ai/eu/v3/telemetry/capabilities?source=TELEMETRY_SOURCE_TRACES" \
  -H "Authorization: Bearer $TOQAN_API_KEY"

Cada entrada de métrica traz seu rótulo, unidade, operações, operação padrão, modos de consulta, tipos de resultado e as dimensões pelas quais pode ser agrupada, incluindo se cada dimensão é agrupável e quais operadores de filtro aceita. Os valores de facetas listam os valores distintos que um campo assume no workspace, para que um filtro possa ser criado a partir de dados reais. Apenas a fonte de traces é compatível: as fontes de métricas e logs respondem 501.

FROM=$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "7 days ago" +%Y-%m-%dT%H:%M:%SZ)
TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -X POST "https://router.toqan.ai/eu/v3/telemetry/facet-values" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\",\"metric\": \"trace_count\",\"field\": \"model\",\"from\": \"$FROM\",\"to\": \"$TO\"}"

Exemplos por caso de uso

Gastos: custo por modelo

genai.cost soma o que foi registrado na janela, group_by divide por modelo e include_totals adiciona o total da janela:

{
  "source": "TELEMETRY_SOURCE_TRACES",
  "from": "2026-05-01T00:00:00Z",
  "to": "2026-05-08T00:00:00Z",
  "compute": [{ "metric": "genai.cost", "op": "sum" }],
  "grain": "day",
  "group_by": ["model"],
  "include_totals": true
}

Erros: traces com falha por Agent

Conte apenas os traces com falha. status aceita ok, error ou unset:

{
  "source": "TELEMETRY_SOURCE_TRACES",
  "from": "2026-05-01T00:00:00Z",
  "to": "2026-05-08T00:00:00Z",
  "compute": [{ "metric": "trace_count", "op": "count" }],
  "grain": "day",
  "group_by": ["agent_name"],
  "filters": [{ "field": "status", "op": "eq", "values": ["error"] }]
}

Latência: p95 por Tool

Uma top list escalar: sem grain, uma linha por tool, ordenada pela métrica:

{
  "source": "TELEMETRY_SOURCE_TRACES",
  "from": "2026-05-01T00:00:00Z",
  "to": "2026-05-08T00:00:00Z",
  "compute": [{ "metric": "duration_ms", "op": "p95" }],
  "mode": "scalar",
  "group_by": ["tool_name"],
  "sort": "desc",
  "limit": 10
}

Logs: volume por severidade

A fonte de logs agrupa pelos campos do OpenTelemetry que armazena, e severity_text traz valores como INFO, WARN ou ERROR:

{
  "source": "TELEMETRY_SOURCE_LOGS",
  "from": "2026-05-01T00:00:00Z",
  "to": "2026-05-02T00:00:00Z",
  "compute": [{ "metric": "log_count", "op": "count" }],
  "grain": "hour",
  "group_by": ["severity_text"]
}

Gastos: custo por dia (bundle)

Obtenha a contagem de solicitações, os tokens e o custo em uma única chamada. Ideal para dashboards de visão geral.

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.usage\", \"op\": \"bundle\"}], \"grain\": \"day\", \"include_totals\": true}"

Gastos: custo por modelo por hora

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"hour\", \"group_by\": [\"model\"]}"

Gastos: BYOK vs. credenciais gerenciadas pelo Toqan Router

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"day\", \"group_by\": [\"credential_type\"]}"

A resposta traz group.credential_type como "orq_managed" ou "customer_byok".

Dimensão de entidade: custo por Agent

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"day\", \"group_by\": [\"agent\"]}"

Dimensão de entidade: custo por Tool com filtro de modelo

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"day\", \"group_by\": [\"tool\"], \"filters\": [{\"field\": \"model\", \"op\": \"in\", \"values\": [\"openai/gpt-5.6-sol\", \"openai/gpt-5.4-mini\"]}]}"

Latência: p95 por modelo

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.latency.p95\", \"op\": \"p95\"}], \"grain\": \"hour\", \"group_by\": [\"model\"]}"

A chave genai.latency.p95:p95 é informada em milissegundos.

Latência: p50, p95 e p99 em paralelo

Cada quantil é uma chamada separada. Dispare três solicitações simultâneas quando precisar dos três.

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)
for pair in genai.latency.p50:p50 genai.latency.p95:p95 genai.latency.p99:p99; do
  curl -X POST "https://router.toqan.ai/eu/v3/telemetry/query" \
    -H "Authorization: Bearer $TOQAN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"source\":\"TELEMETRY_SOURCE_TRACES\",\"from\":\"$FROM\",\"to\":\"$TO\",\"compute\":[{\"metric\":\"${pair%%:*}\",\"op\":\"${pair##*:}\"}],\"grain\":\"hour\"}" &
done
wait

Erros: contagem por provedor

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.errors\", \"op\": \"count\"}], \"grain\": \"hour\", \"group_by\": [\"provider\"]}"

Erros: taxa de erro por modelo (proporção no cliente)

Busque as solicitações e os erros em paralelo e faça a divisão no cliente.

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/v3/telemetry/query" -H "Authorization: Bearer $TOQAN_API_KEY" -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.requests\", \"op\": \"count\"}], \"grain\": \"hour\", \"group_by\": [\"model\"]}" &
curl -X POST "https://router.toqan.ai/eu/v3/telemetry/query" -H "Authorization: Bearer $TOQAN_API_KEY" -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.errors\", \"op\": \"count\"}], \"grain\": \"hour\", \"group_by\": [\"model\"]}" &
wait

Evaluator: taxa de aprovação por Evaluator e versão

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.evaluator.pass_rate\", \"op\": \"rate\"}], \"grain\": \"day\", \"group_by\": [\"evaluator\", \"evaluator_version\"]}"

Evaluator: pontuação média

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.evaluator.score.avg\", \"op\": \"avg\"}], \"grain\": \"day\", \"group_by\": [\"evaluator\"]}"

Evaluator: execuções por rótulo de resultado

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.evaluator.runs\", \"op\": \"count\"}], \"grain\": \"day\", \"group_by\": [\"evaluator\", \"result_label\"]}"

Guardrail: taxa de bloqueio por Evaluator e estágio

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.guardrail.block_rate\", \"op\": \"rate\"}], \"grain\": \"day\", \"group_by\": [\"evaluator\", \"evaluation_stage\"]}"

Guardrail: acionamentos por Policy e estágio

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.guardrail.triggered\", \"op\": \"count\"}], \"grain\": \"day\", \"group_by\": [\"policy\", \"guardrail_stage\"]}"

Guardrail: filtrar por origem

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.guardrail.runs\", \"op\": \"count\"}], \"grain\": \"day\", \"group_by\": [\"evaluator\"], \"filters\": [{\"field\": \"guardrail_origin\", \"op\": \"eq\", \"values\": [\"rule\"]}]}"

Multi-tenant: custo por projeto por dia

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"day\", \"group_by\": [\"project\"]}"

Multi-tenant: uso por chave de API

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.usage\", \"op\": \"bundle\"}], \"grain\": \"day\", \"group_by\": [\"api_key\"], \"include_totals\": true}"

Identity: custo por Identity de usuário final

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"day\", \"group_by\": [\"identity\"]}"

Identity: solicitações filtradas para um único usuário final

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.requests\", \"op\": \"count\"}], \"grain\": \"day\", \"filters\": [{\"field\": \"identity\", \"op\": \"eq\", \"values\": [\"user_42\"]}]}"

Fuso horário: buckets diários em America/New_York

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"day\", \"time_zone\": \"America/New_York\"}"

Os limites dos buckets se alinham à meia-noite no fuso solicitado.

Alta resolução: solicitações por minuto na última hora

FROM=$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d "1 hour ago" +%Y-%m-%dT%H:%M:%SZ)
TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -X POST "https://router.toqan.ai/eu/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.requests\", \"op\": \"count\"}], \"grain\": \"minute\"}"

Entre dimensões: custo por tipo de credencial e modelo

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/v3/telemetry/query" \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": \"TELEMETRY_SOURCE_TRACES\", \"from\": \"$FROM\", \"to\": \"$TO\", \"compute\": [{\"metric\": \"genai.cost\", \"op\": \"sum\"}], \"grain\": \"day\", \"group_by\": [\"credential_type\", \"model\"]}"

O mesmo formato responde às perguntas sobre entidades: troque group_by por provider, product, base_model, project_id, tool_name ou agent_name em traces, service_name ou host_name em logs, e agent, tool ou project nas métricas de uso genai. As métricas de ttft, evaluator e guardrail não aceitam nenhuma dimensão de entidade além de project. Dimensões dinâmicas podem ser endereçadas por prefixo: attributes.* e metadata.* em traces, attribute.*, resource.* e scope.* em logs.

Valores de status de trace

Cada superfície nomeia os mesmos dois resultados de forma diferente. unset é um trace que terminou sem status de erro, e a visualização Traces o considera bem-sucedido.

Resultado	Filtros de OQL e Traces	`status` da Telemetry API	`status_code` do Reporting
Sucesso	`success`	`ok`, `unset`	`OK`
Erro	`error`	`error`	`ERROR`

Erros

Uma consulta rejeitada retorna um envelope JSON com um code numérico, uma message legível e um array details (as respostas 401 e 403 trazem apenas code e message):

{
  "code": 3,
  "message": "invalid filter: unsupported aggregate op \"sum\" for metric \"trace_count\"",
  "details": []
}

HTTP	Código	Motivo
400	3	Métrica desconhecida, uma operação que a métrica não aceita, uma dimensão que não pode ser agrupada, computes genai e brutos na mesma solicitação, mais de um compute em uma consulta genai escalar agrupada, `interval_seconds` em uma métrica genai, um `time_zone` inutilizável, um grain `minute` ou `hour` além da retenção do rollup, ou uma consulta que excede um orçamento.
501	12	Valores de facetas solicitados para uma fonte diferente de traces.
401	16	Token bearer ausente ou forjado.
403	7	A chave de API não tem o domínio por trás da fonte solicitada: `traces-read`, `reporting-read` ou `logs-read`.
415	3	O corpo da solicitação não é JSON.
500	13	Falha inesperada no backend. Entre em contato com o suporte se persistir.

Toda resposta de consulta bem-sucedida inclui meta.request_id. Inclua-o nos tickets de suporte para uma correlação rápida dos logs.

As rejeições por orçamento trazem um detalhe ErrorInfo que nomeia o recurso esgotado (range_days, buckets, rows, series ou metric_values) e seu limite; em todas as fontes, exceto métricas genai, um estouro de buckets também informa a quantidade necessária.

Limites

Limite	Valor
Janela de consulta	90 dias; todas as fontes, exceto métricas brutas de traces, também respeitam o período de retenção do workspace. Em métricas genai, um grain `minute` explícito também exige `from` dentro de 14 dias, e `hour` dentro de 90 dias
Entradas `compute`	10
`group_by`	5 dimensões
`filters`	20 entradas, 100 valores cada
`limit`	5000 (padrão 100)
Resultado de série temporal	5000 linhas, 5000 buckets, 50000 valores de métricas
`interval_seconds`	1 a 86400
Execução	30 segundos

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Uso e custo

Agregados de traces

Volume de logs

Descubra a superfície

Endpoint

Consultar telemetria

Listar capacidades

Listar valores de facetas

Início rápido

Solicitação

Resposta

Fontes e métricas

Descubra o que está disponível

Exemplos por caso de uso

Valores de status de trace

Erros

Limites

Uso e custo

Agregados de traces

Volume de logs

Descubra a superfície

​Endpoint

Consultar telemetria

Listar capacidades

Listar valores de facetas

​Início rápido

​Solicitação

​Resposta

​Fontes e métricas

​Descubra o que está disponível

​Exemplos por caso de uso

​Valores de status de trace

​Erros

​Limites

Endpoint

Início rápido

Solicitação

Resposta

Fontes e métricas

Descubra o que está disponível

Exemplos por caso de uso

Valores de status de trace

Erros

Limites