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

# Track usage by identity

> Group AI metrics by user, team, project, or client. Create identities via API to organize analytics and monitor usage patterns across your organization.

See [HTTP URLs and authentication](/docs/reference/base-urls.md) and the API reference for complete request and response formats.

**Identities** are entities used to tie metrics within the **Toqan Router** APIs.

They can represent:

* a **User**
* a **Team**
* a **Project**
* a **Client**

**Identities** are created via the **AI Studio**, **AI Gateway**, or the API and then used as supplementary data to attribute metrics within any other call of the API.

The list shows **External ID**, **Name**, **Source**, **Requests**, **Cost \$**, **Tokens**, and **Error rate**, and the sort control reads **Sort: Last updated**. The same identities appear as the **Identity** filter in [**Traces**](/docs/ai-studio/observability/traces.md), which narrows a trace list to the identity that a request was attributed to.

For the full set of ways to attach context to a request, including app name, threads, and custom metadata, see [Request Metadata](/docs/ai-gateway/request-metadata.md).

## Creating an identity

> [tab] AI Studio
>
> Head to the **Identities** section and choose **Create an Identity**.
>
> The following panel opens:

> [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]
> >
> > See the [API Reference](/docs/reference/identities/create-an-identity.md) for the full parameter specification.

## Attaching an identity to a request

Every request can be attributed to a specific user, team, or client. The gateway checks each of the following sources in order and uses the first match found:

| Order | Source | Effect |
| - | - | - |
| 1 | `identity` object in the request body | Tags the request and upserts the identity record (name, email, metadata) |
| 2 | `X-TOQAN-IDENTITY-ID` request header | Tags the request only; does not update the identity record |
| 3 | API key owner | Tags the request only; applies automatically when the key is user-owned |

> [tab] Body
>
> Pass an `identity` object on each **Agent** response or **Deployment** invocation to attribute the request to an **Identity**.
>
> > [!NOTE]
> >
> > The `identityId` / `identity_id` constructor option was removed in SDK v4.10.0. Pass `identity` on each request instead.
>
> **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": "<external_id>"}
> }'
> ```

> [tab] X-TOQAN-IDENTITY-ID Header
>
> Use the `X-TOQAN-IDENTITY-ID` header to tag a request without modifying the body. Useful in middleware or proxy layers where the payload is opaque.
>
> > [!NOTE]
> >
> > The header tags the request with the identity ID only. The identity record is created from the trace when it does not exist, with no display name, email, or metadata. Use the body `identity` object or [Create identity](/docs/reference/identities/create-an-identity.md) to set those fields.
>
> **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] API Key Owner
>
> When a request includes no `identity` body field and no `X-TOQAN-IDENTITY-ID` header, the request is automatically attributed to the API key's owner, provided the key is user-owned. No additional configuration is required.

## Retrieving an identity via the API

Once an identity is in use, you can fetch its full record at any time using its `_id` (ULID) or `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"
```

The response returns the full identity record:

```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]
>
> See the [API Reference](/docs/reference/identities/retrieve-an-identity.md) for the full parameter and response specification.

## Listing identities with metrics

Pass `include_metrics=true` to the list endpoint to include 30-day usage metrics for each identity in the response. This is useful for auditing spend, spotting high error rates, or building identity-level dashboards.

```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"
```

Each identity in the response includes a `metrics` object with usage data for the last 30 days:

```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
}
```

| Field | Description |
| - | - |
| `total_cost` | Total spend in USD over the last 30 days |
| `total_tokens` | Total tokens consumed over the last 30 days |
| `total_requests` | Total number of requests made over the last 30 days |
| `error_rate` | Ratio of failed requests over the last 30 days (e.g. `0.33` = 33% of requests returned an error) |

> [!NOTE]
>
> See the [API Reference](/docs/reference/identities/list-identities.md) for the full list of query parameters including pagination, search, and tag filtering.

## Budget control

Attach a spending limit to an identity to cap cost, token usage, or request rate for a specific customer or tenant. Navigate to **Settings > Budgets**, click **Create**, set **Scope > Applies to** to **Identity**, then select the target identity by external ID.

See [Budgets](/docs/ai-gateway/budgets.md) for the full list of configurable limits, reset periods, and alerts.

## Identity field reference

Fields on the `identity` object attached to an inference request:

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique identity identifier (max 255 characters) |
| `display_name` | string | No | Human-readable name |
| `email` | string | No | Email address |
| `avatar_url` | string | No | URL to a profile image, set when the identity is created with the [Identities API](/docs/reference/identities/create-an-identity.md). |
| `metadata` | object | No | Free-form JSON metadata. Values can include nested objects and arrays. |
| `tags` | string\[] | No | Classification tags for segmentation (max 10) |

## Best practices

* **Consistent IDs**: Use predictable identity ID patterns (e.g. `user-{userId}`, `tenant-{orgId}-{userId}`) across the application.
* **Essential metadata only**: Include only relevant metadata fields to minimize payload size.
* **Tag strategy**: Use tags for filtering and segmentation rather than storing detailed data.
* **Privacy compliance**: Ensure identity data handling meets applicable privacy requirements.
* **Validation**: Validate `id` format and length before sending requests.

## Troubleshooting

| Issue | Cause | Solution |
| - | - | - |
| Identity not appearing in analytics | Missing or invalid `identity.id` | Ensure `identity.id` is provided and non-empty |
| Duplicate identities in the dashboard | Inconsistent ID format across requests | Standardize identity ID generation in one place |


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