Metadados da requisição

Casos de uso

Atribuir requisições a um app ou serviço

Dê um nome a cada requisição para segmentar custo e desempenho por produto, funcionalidade ou ambiente.

Agrupar análises por usuário final ou tenant

Anexe uma Identity para que gastos, latência e taxas de erro sejam atribuídos a um usuário, equipe ou cliente, com orçamentos opcionais por identidade.

Agrupar conversas com vários turnos

Marque cada turno com um ID de Thread para que a conversa completa seja agrupada na observabilidade.

Segmentar análises por contexto de negócio

Anexe metadados de chave-valor, como plano, canal ou feature flag, e filtre os traces por esses campos.

Visão geral

Toda requisição do AI Gateway pode levar contexto por meio de vários mecanismos:

name: identifica o app ou serviço
identity: identifica o usuário final ou tenant
thread: agrupa uma conversa
metadata: leva contexto de negócio

Cada mecanismo responde a uma pergunta e aparece em seu próprio canal. Use a tabela de decisão abaixo para escolher o mecanismo para cada pergunta. variables também acompanham a requisição, mas preenchem templates de prompt em vez de descrever a requisição. O passo a passo de cada mecanismo está em App Tracking, Identities e Thread Management; a referência dos atributos de span está em Metadata.

Qual mecanismo usar

Mecanismo	Responde à pergunta	Use quando
`name`	Qual app, serviço ou funcionalidade fez esta chamada?	Custo e desempenho por linha de produto, com um conjunto fixo de superfícies conhecidas
`identity`	Para qual usuário final, equipe ou cliente é esta requisição?	Atribuição por usuário, faturamento por tenant, orçamentos por identidade
`thread`	A qual conversa ou fluxo de trabalho esta requisição pertence?	Chats com vários turnos, fluxos de agentes com várias etapas, tickets de suporte
`metadata`	Que contexto de negócio se aplica a esta requisição?	Segmentação por chave-valor por plano, canal, região ou feature flag

Início rápido

Envie uma requisição com os quatro mecanismos anexados.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Refund my order",
    "name": "SupportAssistant-Production",
    "metadata": {
      "customer_tier": "premium",
      "channel": "email"
    },
    "thread": {
      "id": "conversation-abc123",
      "tags": ["user-123"]
    },
    "identity": {
      "id": "user_123"
    }
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "openai/gpt-5.4-mini",
  input: "Refund my order",
  name: "SupportAssistant-Production",
  metadata: { customer_tier: "premium", channel: "email" },
  thread: { id: "conversation-abc123", tags: ["user-123"] },
  identity: { id: "user_123" },
});

console.log(response.output_text);

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Refund my order",
    extra_body={
        "name": "SupportAssistant-Production",
        "metadata": {"customer_tier": "premium", "channel": "email"},
        "thread": {"id": "conversation-abc123", "tags": ["user-123"]},
        "identity": {"id": "user_123"},
    },
)

print(response.output_text)

Configuração

Parâmetro	Tipo	Filtro de trace	Descrição
`name`	string	Name	Nome de exibição no trace. Recomendado: apenas caracteres alfanuméricos e hifens, menos de 50 caracteres, sem timestamps ou valores dinâmicos.
`metadata`	object	`metadata.<key>`	Pares de chave-valor com valores do tipo string. Na Responses API, valores que não são string são rejeitados com um 400.
`thread`	object	Thread ID	Agrupa requisições relacionadas: `id` (obrigatório) mais `tags` opcionais.
`identity`	object	Identity	Atribui a requisição a um usuário final: `id` (obrigatório) mais `display_name`, `email`, `metadata` e `tags` opcionais.
`variables`	object	—	Variáveis de template para substituição no prompt. Passe segredos como `{"secret": true, "value": "..."}` para que sejam ocultados nos traces.

Em /v3/router/chat/completions:

metadata é limitado a 16 pares de chave-valor, com chaves de até 64 caracteres e valores de até 512 caracteres
thread e identity são passados dentro do objeto orq (orq.thread, orq.identity)
name é passado no nível superior

Headers

Clientes que não conseguem modificar o corpo da requisição, como agentes de programação, anexam metadados, identidade e contexto de thread por meio de headers. X-TOQAN-IDENTITY-ID e X-TOQAN-THREAD-ID são lidos em todas as requisições do AI Gateway. X-TOQAN-METADATA-<key> e X-TOQAN-METADATA são lidos nos endpoints de inferência: /v3/router/responses, /v3/anthropic/v1/messages, /v3/google/v1beta/models/* e /v3/google/v1beta/interactions, além dos endpoints /v3/router/* de completions, embeddings, imagem, áudio, moderação, OCR e rerank.

Header	Define	Exemplo
`X-TOQAN-METADATA-<key>`	Uma chave de metadados por header. A chave é o sufixo do header em minúsculas.	`X-TOQAN-METADATA-REPO: acme-api` define `metadata.repo` como `acme-api`.
`X-TOQAN-METADATA`	Várias chaves de metadados em um único header: uma lista `key=value` separada por vírgulas ou um objeto JSON.	`X-TOQAN-METADATA: repo=acme-api,ticket=PROJ-123`
`X-TOQAN-IDENTITY-ID`	O ID da identidade. Consulte Identities.	`X-TOQAN-IDENTITY-ID: user_123`
`X-TOQAN-THREAD-ID`	O ID da thread.	`X-TOQAN-THREAD-ID: conversation-abc123`

Quando o valor de X-TOQAN-METADATA começa com {, ele é interpretado como um objeto JSON em vez do formato separado por vírgulas. Valores string, número e booleano são mantidos; valores objeto, array e null são ignorados. Somente nos endpoints Anthropic Messages e Google, uma lista fixa de headers permitidos (user-agent, originator, session-id, session_id, thread-id, x-app, x-claude-code-session-id, x-codex-beta-features, anthropic-beta, anthropic-version, anthropic-dangerous-direct-browser-access) é capturada automaticamente nos metadados, quando presente, para identificar o assistente de programação que fez a chamada. Nenhum outro endpoint captura esses headers automaticamente.

Precedência quando a mesma chave de metadados é definida mais de uma vez: o objeto metadata do corpo prevalece, depois os headers X-TOQAN-METADATA-<key>, depois o header X-TOQAN-METADATA e, somente nos endpoints Anthropic Messages e Google, a lista de headers capturados automaticamente acima.

Limites: até 20 chaves de metadados por requisição vindas de X-TOQAN-METADATA e X-TOQAN-METADATA-<key> somadas. Nesses endpoints, os headers da lista capturada automaticamente não contam para esse limite. As chaves devem ter 64 caracteres ou menos e corresponder a [a-z0-9._-]+. Valores com mais de 256 caracteres são truncados. Entradas que não atendem a essas regras são descartadas silenciosamente; a requisição ainda é concluída com sucesso. Os metadados derivados de headers chegam aos Traces como atributos de span metadata.<key> em todos os endpoints listados acima e podem ser filtrados da mesma forma que os metadados do corpo. Eles nunca são encaminhados ao provedor do modelo. Em endpoints que recebem um corpo JSON, X-TOQAN-METADATA e X-TOQAN-METADATA-<key> também ficam disponíveis para regras de roteamento, regras de guardrail e orçamentos, de modo que quem consegue definir headers em uma requisição pode influenciar quais dessas regras correspondem. Endpoints que recebem uploads multipart (transcrição, tradução, edição de imagem, variação de imagem) colocam os metadados dos headers apenas nos traces. A lista capturada automaticamente acima nunca é usada na correspondência de regras, em nenhum endpoint.

curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TOQAN-METADATA-REPO: acme-api" \
  -H "X-TOQAN-METADATA-TICKET: PROJ-123" \
  -H "X-TOQAN-THREAD-ID: conversation-abc123" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Refund my order"
  }'

Boas práticas

Mantenha baixa a cardinalidade dos nomes de app: use um conjunto pequeno e fixo de nomes de app (cerca de 50 por workspace) com padrões consistentes, como Service-Environment. Evite timestamps ou valores dinâmicos, que fragmentam as análises.
Use um conjunto fixo de chaves de metadados: defina um conjunto pequeno de chaves (customer_tier, channel, region) e reutilize-as. Chaves de alta cardinalidade, como IDs de requisição ou timestamps, inviabilizam a filtragem e aumentam o armazenamento.
IDs de thread: use UUIDs ou chaves compostas, como user-{userId}-{sessionId}, para evitar colisões entre sessões.
IDs de identidade: use padrões previsíveis, como user-{userId} ou tenant-{tenantId}, para que as identidades permaneçam consistentes entre as requisições.
Um mecanismo por pergunta: se o valor descreve o app, use name; se descreve o usuário, use identity; se é contexto de negócio, use metadata.

O que não armazenar nos metadados da requisição

Dados pessoais (PII): não coloque e-mails, números de telefone ou dados pessoais em metadata, name ou thread.tags; eles persistem nos traces armazenados. Para manter valores sensíveis fora dos traces armazenados, inclua "metadata" em security.mask ou habilite a PII Redaction.
Segredos: passe tokens e chaves como variáveis de template com {"secret": true, "value": "..."} para que sejam ocultados nos traces. Consulte Run Agents para a referência de variáveis.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Visão geral

Qual mecanismo usar

Início rápido

Configuração

Headers

Boas práticas

O que não armazenar nos metadados da requisição

​Visão geral

​Qual mecanismo usar

​Início rápido

​Configuração

​Headers

​Boas práticas

​O que não armazenar nos metadados da requisição

Visão geral

Qual mecanismo usar

Início rápido

Configuração

Headers

Boas práticas

O que não armazenar nos metadados da requisição