> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Metadados da requisição > Anexe nome do app, identidade, ID de thread e metadados personalizados às requisições do AI Gateway para segmentar custo, latência e traces na observabilidade. **Casos de uso** > [accordion] 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. > [accordion] 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. > [accordion] Agrupar conversas com vários turnos > > Marque cada turno com um ID de **Thread** para que a conversa completa seja agrupada na observabilidade. > [accordion] 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](/docs/pt-BR/ai-gateway/app-tracking.md), [Identities](/docs/pt-BR/ai-studio/observability/identities.md) e [Thread Management](/docs/pt-BR/ai-gateway/thread-management.md); a referência dos atributos de span está em [Metadata](/docs/pt-BR/ai-studio/observability/span-attributes.md). ## 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. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} 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" } }' ``` ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}} 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); ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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.` | 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. | > [!NOTE] > > 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-` 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-` | 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](/docs/pt-BR/ai-studio/observability/identities.md). | `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. > [!NOTE] > > 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-`, 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-` 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](/docs/pt-BR/ai-studio/observability/traces.md) como atributos de span `metadata.` 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-` 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. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} 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`](/docs/pt-BR/ai-gateway/features/security) ou habilite a [PII Redaction](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md). * **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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.