> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry API

> Consulte traces, logs e métricas de uso por meio de um único endpoint: latência, custo e throughput de saída em um único formato de resposta por fonte.

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.

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.

> [!NOTE]
>
> 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](/docs/pt-BR/ai-studio/observability/reporting-api.md) está obsoleta em favor dela. Os endpoints de agregados de traces continuam com suporte para os chamadores existentes.

> [card] [Uso e custo](#examples-by-use-case)
>
> Agrupe métricas genai por modelo, provedor, projeto, agent ou tool.

> [card] [Agregados de traces](#sources-and-metrics)
>
> Conte traces e spans e obtenha percentis de latência ou totais de tokens e custo.

> [card] [Volume de logs](#sources-and-metrics)
>
> Conte registros de log e registros de erro, agrupados por severidade ou serviço.

> [card] [Descubra a superfície](#discover-what-is-available)
>
> 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.

> [card] [Consultar telemetria](/docs/pt-BR/reference/telemetry/query-telemetry.md)
>
> Esquema completo de `POST /v3/telemetry/query`.

> [card] [Listar capacidades](/docs/pt-BR/reference/telemetry/list-telemetry-capabilities.md)
>
> `GET /v3/telemetry/capabilities`.

> [card] [Listar valores de facetas](/docs/pt-BR/reference/telemetry/list-telemetry-facet-values.md)
>
> `POST /v3/telemetry/facet-values`.

## Início rápido

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

```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/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](/docs/pt-BR/ai-studio/observability/oql.md) (`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:

```json Envelope theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

> [accordion] 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:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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
> }
> ```

> [accordion] Erros: traces com falha por Agent
>
> Conte apenas os traces com falha. `status` aceita `ok`, `error` ou `unset`:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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"] }]
> }
> ```

> [accordion] Latência: p95 por Tool
>
> Uma top list escalar: sem grain, uma linha por tool, ordenada pela métrica:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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
> }
> ```

> [accordion] 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`:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>   "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"]
> }
> ```

> [accordion] 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.
>
> ```bash wrap 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/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}"
> ```

> [accordion] Gastos: custo por modelo por hora
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Gastos: BYOK vs. credenciais gerenciadas pelo Toqan Router
>
> ```bash wrap 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/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"`.

> [accordion] Dimensão de entidade: custo por Agent
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Dimensão de entidade: custo por Tool com filtro de modelo
>
> ```bash wrap 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/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\"]}]}"
> ```

> [accordion] Latência: p95 por modelo
>
> ```bash wrap 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/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.

> [accordion] 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.
>
> ```bash wrap 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)
> 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
> ```

> [accordion] Erros: contagem por provedor
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] 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.
>
> ```bash wrap 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/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
> ```

> [accordion] Evaluator: taxa de aprovação por Evaluator e versão
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Evaluator: pontuação média
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Evaluator: execuções por rótulo de resultado
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Guardrail: taxa de bloqueio por Evaluator e estágio
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Guardrail: acionamentos por Policy e estágio
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Guardrail: filtrar por origem
>
> ```bash wrap 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/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\"]}]}"
> ```

> [accordion] Multi-tenant: custo por projeto por dia
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Multi-tenant: uso por chave de API
>
> ```bash wrap 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/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}"
> ```

> [accordion] Identity: custo por Identity de usuário final
>
> ```bash wrap 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/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\"]}"
> ```

> [accordion] Identity: solicitações filtradas para um único usuário final
>
> ```bash wrap 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/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\"]}]}"
> ```

> [accordion] Fuso horário: buckets diários em America/New\_York
>
> ```bash wrap 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/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.

> [accordion] Alta resolução: solicitações por minuto na última hora
>
> ```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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\"}"
> ```

> [accordion] Entre dimensões: custo por tipo de credencial e modelo
>
> ```bash wrap 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/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`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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. |

> [!TIP]
>
> 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.