Acompanhar o uso por identidade

Consulte URLs e autenticação HTTP 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, 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.

Criar uma identidade

AI Studio
API / SDK

Acesse a seção Identities e escolha Create an Identity.O seguinte painel é aberto:

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"
    }
}'

Consulte a Referência da API 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

Corpo
Cabeçalho X-TOQAN-IDENTITY-ID
Proprietário da chave de API

Passe um objeto identity em cada resposta de Agent ou invocação de Deployment para atribuir a solicitação a uma Identity.

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

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": "<external_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.

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 para definir esses campos.

Agents

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"
}'

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.

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:

{
  "_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"
}

Consulte a Referência da API 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.

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:

{
  "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)

Consulte a Referência da API 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 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.
`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

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Criar uma identidade

Anexar uma identidade a uma solicitação

Obter uma identidade pela API

Listar identidades com métricas

Controle de orçamento

Referência dos campos de identidade

Boas práticas

Solução de problemas

​Criar uma identidade

​Anexar uma identidade a uma solicitação

​Obter uma identidade pela API

​Listar identidades com métricas

​Controle de orçamento

​Referência dos campos de identidade

​Boas práticas

​Solução de problemas

Criar uma identidade

Anexar uma identidade a uma solicitação

Obter uma identidade pela API

Listar identidades com métricas

Controle de orçamento

Referência dos campos de identidade

Boas práticas

Solução de problemas