> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Acompanhar o uso por identidade > Agrupe métricas de IA por usuário, equipe, projeto ou cliente. Crie identidades pela API para organizar as análises e monitorar padrões de uso em toda a sua organização. 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. **Identities** são entidades usadas para vincular métricas nas APIs do **Toqan Router**. Elas podem representar: * um **Usuário** * uma **Equipe** * um **Projeto** * um **Cliente** As **Identities** são criadas pelo **AI Studio**, pelo **AI Gateway** ou pela API e depois usadas como dados complementares para atribuir métricas em qualquer outra chamada da API. A lista mostra **External ID**, **Name**, **Source**, **Requests**, **Cost \$**, **Tokens** e **Error rate**, e o controle de ordenação exibe **Sort: Last updated**. As mesmas identidades aparecem como o filtro **Identity** em [**Traces**](/docs/pt-BR/ai-studio/observability/traces.md), que restringe uma lista de traces à identidade à qual uma solicitação foi atribuída. Para ver todas as formas de anexar contexto a uma solicitação, incluindo nome do app, threads e metadados personalizados, consulte [Request Metadata](/docs/pt-BR/ai-gateway/request-metadata.md). ## Criar uma identidade > [tab] AI Studio > > Acesse a seção **Identities** e escolha **Create an Identity**. > > O seguinte painel é aberto: > [tab] API / SDK > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl --location 'https://router.toqan.ai/eu/v2/identities' \ > --header "Authorization: Bearer $TOQAN_API_KEY" \ > --header 'Content-Type: application/json' \ > --data-raw '{ > "external_id": "user_123", > "display_name": "John Smith", > "email": "john@acme.com", > "metadata": { > "role": "admin" > } > }' > ``` > > > [!NOTE] > > > > Consulte a [Referência da API](/docs/pt-BR/reference/identities/create-an-identity.md) para ver a especificação completa dos parâmetros. ## Anexar uma identidade a uma solicitação Toda solicitação pode ser atribuída a um usuário, equipe ou cliente específico. O gateway verifica cada uma das fontes a seguir, na ordem, e usa a primeira correspondência encontrada: | Ordem | Fonte | Efeito | | - | - | - | | 1 | Objeto `identity` no corpo da solicitação | Marca a solicitação e cria ou atualiza o registro da identidade (nome, e-mail, metadados) | | 2 | Cabeçalho de solicitação `X-TOQAN-IDENTITY-ID` | Apenas marca a solicitação; não atualiza o registro da identidade | | 3 | Proprietário da chave de API | Apenas marca a solicitação; aplicado automaticamente quando a chave pertence a um usuário | > [tab] Corpo > > Passe um objeto `identity` em cada resposta de **Agent** ou invocação de **Deployment** para atribuir a solicitação a uma **Identity**. > > > [!NOTE] > > > > A opção de construtor `identityId` / `identity_id` foi removida no SDK v4.10.0. Em vez disso, passe `identity` em cada solicitação. > > **Agents** > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl 'https://router.toqan.ai/eu/v3/router/responses' \ > -H "Authorization: Bearer $TOQAN_API_KEY" \ > -H 'Content-Type: application/json' \ > --data-raw '{ > "model": "openai/gpt-4.1-mini", > "input": "Hello", > "identity": {"id": ""} > }' > ``` > [tab] Cabeçalho X-TOQAN-IDENTITY-ID > > Use o cabeçalho `X-TOQAN-IDENTITY-ID` para marcar uma solicitação sem modificar o corpo. É útil em camadas de middleware ou proxy em que o payload é opaco. > > > [!NOTE] > > > > O cabeçalho marca a solicitação apenas com o ID da identidade. O registro da identidade é criado a partir do trace quando ainda não existe, sem nome de exibição, e-mail ou metadados. Use o objeto `identity` no corpo ou [Create identity](/docs/pt-BR/reference/identities/create-an-identity.md) para definir esses campos. > > **Agents** > > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl 'https://router.toqan.ai/eu/v3/router/responses' \ > -H "Authorization: Bearer $TOQAN_API_KEY" \ > -H "X-TOQAN-IDENTITY-ID: user_123" \ > -H 'Content-Type: application/json' \ > --data-raw '{ > "model": "openai/gpt-4.1-mini", > "input": "Hello" > }' > ``` > [tab] Proprietário da chave de API > > Quando uma solicitação não inclui o campo `identity` no corpo nem o cabeçalho `X-TOQAN-IDENTITY-ID`, ela é atribuída automaticamente ao proprietário da chave de API, desde que a chave pertença a um usuário. Nenhuma configuração adicional é necessária. ## Obter uma identidade pela API Depois que uma identidade estiver em uso, você pode obter o registro completo a qualquer momento usando seu `_id` (ULID) ou `external_id`. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request GET \ --url "https://router.toqan.ai/eu/v2/identities/01ARZ3NDEKTSV4RRFFQ69G5FAV" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $TOQAN_API_KEY" ``` A resposta retorna o registro completo da identidade: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "external_id": "user_12345", "display_name": "John Smith", "email": "john.smith@example.com", "avatar_url": "https://example.com/avatars/john-smith.jpg", "tags": ["premium", "beta-user"], "metadata": { "department": "Engineering", "role": "Senior Developer", "subscription_tier": "premium" }, "created": "2024-01-15T10:30:00Z", "updated": "2024-01-15T10:30:00Z" } ``` > [!NOTE] > > Consulte a [Referência da API](/docs/pt-BR/reference/identities/retrieve-an-identity.md) para ver a especificação completa dos parâmetros e da resposta. ## Listar identidades com métricas Passe `include_metrics=true` para o endpoint de listagem para incluir na resposta as métricas de uso dos últimos 30 dias de cada identidade. Isso é útil para auditar gastos, identificar taxas de erro elevadas ou criar dashboards por identidade. ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request GET \ --url 'https://router.toqan.ai/eu/v2/identities?include_metrics=true' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header "Authorization: Bearer $TOQAN_API_KEY" ``` Cada identidade na resposta inclui um objeto `metrics` com os dados de uso dos últimos 30 dias: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "object": "list", "data": [ { "_id": "01KJ9YV9DH28W3G9ZJFKQ1Q8Q4", "external_id": "user_12345", "display_name": "John Doe", "email": "john.doe@example.com", "tags": ["hr", "engineering"], "created": "2026-02-25T08:32:31.153Z", "updated": "2026-02-25T08:32:31.153Z", "metrics": { "total_cost": 0.011691, "total_tokens": 1626, "total_requests": 3, "error_rate": 0.3333333333333333 } } ], "has_more": false } ``` | Campo | Descrição | | - | - | | `total_cost` | Gasto total em USD nos últimos 30 dias | | `total_tokens` | Total de tokens consumidos nos últimos 30 dias | | `total_requests` | Número total de solicitações feitas nos últimos 30 dias | | `error_rate` | Proporção de solicitações com falha nos últimos 30 dias (por exemplo, `0.33` = 33% das solicitações retornaram um erro) | > [!NOTE] > > Consulte a [Referência da API](/docs/pt-BR/reference/identities/list-identities.md) para ver a lista completa de parâmetros de consulta, incluindo paginação, busca e filtragem por tags. ## Controle de orçamento Anexe um limite de gastos a uma identidade para limitar o custo, o uso de tokens ou a taxa de solicitações de um cliente ou tenant específico. Acesse **Settings > Budgets**, clique em **Create**, defina **Scope > Applies to** como **Identity** e selecione a identidade de destino pelo ID externo. Consulte [Budgets](/docs/pt-BR/ai-gateway/budgets.md) para ver a lista completa de limites configuráveis, períodos de redefinição e alertas. ## Referência dos campos de identidade Campos do objeto `identity` anexado a uma solicitação de inferência: | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `id` | string | Sim | Identificador único da identidade (máximo de 255 caracteres) | | `display_name` | string | Não | Nome legível | | `email` | string | Não | Endereço de e-mail | | `avatar_url` | string | Não | URL de uma imagem de perfil, definida quando a identidade é criada com a [Identities API](/docs/pt-BR/reference/identities/create-an-identity.md). | | `metadata` | object | Não | Metadados JSON de formato livre. Os valores podem incluir objetos e arrays aninhados. | | `tags` | string\[] | Não | Tags de classificação para segmentação (máximo de 10) | ## Boas práticas * **IDs consistentes**: use padrões previsíveis de ID de identidade (por exemplo, `user-{userId}`, `tenant-{orgId}-{userId}`) em toda a aplicação. * **Apenas metadados essenciais**: inclua somente campos de metadados relevantes para minimizar o tamanho do payload. * **Estratégia de tags**: use tags para filtragem e segmentação, em vez de armazenar dados detalhados. * **Conformidade com privacidade**: garanta que o tratamento dos dados de identidade atenda aos requisitos de privacidade aplicáveis. * **Validação**: valide o formato e o comprimento do `id` antes de enviar as solicitações. ## Solução de problemas | Problema | Causa | Solução | | - | - | - | | A identidade não aparece nas análises | `identity.id` ausente ou inválido | Garanta que `identity.id` seja informado e não esteja vazio | | Identidades duplicadas no dashboard | Formato de ID inconsistente entre solicitações | Padronize a geração de IDs de identidade em um único lugar | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.