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

# Identity tracking for user analytics

> Monitor LLM usage per user or identity. Track individual AI interactions, costs, and patterns for personalization, billing, and user behavior analytics.

Associate requests with [Identity](/docs/ai-studio/observability/identities) identifiers for user-level observability and analytics.

<Info>
  [Identities](/docs/ai-studio/observability/identities) are **Orq.ai** entities used to track project expenses and token usage per user or team.
</Info>

## Why use identity tracking

* Per-user cost attribution and cross-charging to tenants or customers.
* Enforcing per-user rate limits to prevent abuse.
* Identifying which users generate the most load or cost.
* Linking LLM usage to existing user analytics for cohort analysis.

## Use Cases

| Scenario             | Identity ID Strategy      | Metadata Example                                  |
| -------------------- | ------------------------- | ------------------------------------------------- |
| **User Analytics**   | `user-{userId}`           | `[{"plan": "pro", "usage_tier": "high"}]`         |
| **Customer Support** | `support-{ticketId}`      | `[{"priority": "high", "issue_type": "billing"}]` |
| **A/B Testing**      | `test-{userId}-{variant}` | `[{"experiment": "pricing-v2", "variant": "b"}]`  |
| **Multi-tenant**     | `tenant-{orgId}-{userId}` | `[{"org": "acme-corp", "role": "admin"}]`         |

## Quick Start

Pass a stable identifier from the system (a database user ID, UUID, or similar string) as `identity.id` on any request.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/router/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "input": "How can I upgrade my account?",
      "identity": {
        "id": "user_123",
        "display_name": "John Smith",
        "email": "john@example.com",
        "metadata": [{"plan": "premium", "signup_date": "2024-01-15"}]
      }
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const response = await client.responses.create({
    model: "openai/gpt-4o",
    input: "How can I upgrade my account?",
    extra_body: {
      identity: {
        id: "user_123",
        display_name: "John Smith",
        email: "john@example.com",
        metadata: [{ plan: "premium", signup_date: "2024-01-15" }],
      },
    },
  });

  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("ORQ_API_KEY"),
      base_url="https://api.orq.ai/v3/router",
  )

  response = client.responses.create(
      model="openai/gpt-4o",
      input="How can I upgrade my account?",
      extra_body={
          "identity": {
              "id": "user_123",
              "display_name": "John Smith",
              "email": "john@example.com",
              "metadata": [{"plan": "premium", "signup_date": "2024-01-15"}],
          }
      },
  )

  print(response.output_text)
  ```

  ```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from openai import OpenAI
  import os

  client = OpenAI(
      api_key=os.environ.get("ORQ_API_KEY"),
      base_url="https://api.orq.ai/v3/router",
  )

  response = client.chat.completions.create(
      model="openai/gpt-4o",
      messages=[{"role": "user", "content": "How can I upgrade my account?"}],
      extra_body={
          "identity": {
              "id": "user_123",
              "display_name": "John Smith",
              "email": "john@example.com",
              "metadata": [{"plan": "premium", "signup_date": "2024-01-15"}],
          }
      },
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const response = await client.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "How can I upgrade my account?" }],
    extra_body: {
      identity: {
        id: "user_123",
        display_name: "John Smith",
        email: "john@example.com",
        metadata: [{ plan: "premium", signup_date: "2024-01-15" }],
      },
    },
  });
  ```
</CodeGroup>

## Identity resolution

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-ORQ-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  |

<Tabs>
  <Tab title="Body">
    Pass the `identity` object in the request body to attribute the request and keep the identity record up to date. See the Quick Start above for full examples.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.orq.ai/v3/router/chat/completions \
        -H "Authorization: Bearer $ORQ_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "openai/gpt-4o",
          "messages": [{"role": "user", "content": "Hello"}],
          "identity": {
            "id": "user_123",
            "display_name": "John Smith",
            "email": "john@example.com"
          }
        }'
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import OpenAI from "openai";

      const client = new OpenAI({
        apiKey: process.env.ORQ_API_KEY,
        baseURL: "https://api.orq.ai/v3/router",
      });

      const response = await client.chat.completions.create({
        model: "openai/gpt-4o",
        messages: [{ role: "user", content: "Hello" }],
        extra_body: {
          identity: { id: "user_123", display_name: "John Smith", email: "john@example.com" },
        },
      });
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      from openai import OpenAI
      import os

      client = OpenAI(
          api_key=os.environ.get("ORQ_API_KEY"),
          base_url="https://api.orq.ai/v3/router",
      )

      response = client.chat.completions.create(
          model="openai/gpt-4o",
          messages=[{"role": "user", "content": "Hello"}],
          extra_body={
              "identity": {"id": "user_123", "display_name": "John Smith", "email": "john@example.com"},
          },
      )
      ```
    </CodeGroup>
  </Tab>

  <Tab title="X-ORQ-IDENTITY-ID Header">
    Use the `X-ORQ-IDENTITY-ID` header to tag a request without modifying the body. Useful in middleware or proxy layers where the payload is opaque.

    <Note>
      The `X-ORQ-IDENTITY-ID` header does not upsert the identity record. Use the body `identity` object to keep the identity's display name, email, and metadata up to date.
    </Note>

    <Warning>
      The identity must already exist before using this header. If no identity with the given ID has been created via the body method or the [Create identity](/reference/identities/create-an-identity) endpoint, the request is processed but the tag is not attributed to any identity record.
    </Warning>

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.orq.ai/v3/router/chat/completions \
        -H "Authorization: Bearer $ORQ_API_KEY" \
        -H "X-ORQ-IDENTITY-ID: user_123" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "openai/gpt-4o",
          "messages": [{"role": "user", "content": "Hello"}]
        }'
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import OpenAI from "openai";

      const client = new OpenAI({
        apiKey: process.env.ORQ_API_KEY,
        baseURL: "https://api.orq.ai/v3/router",
      });

      const response = await client.chat.completions.create(
        { model: "openai/gpt-4o", messages: [{ role: "user", content: "Hello" }] },
        { headers: { "X-ORQ-IDENTITY-ID": "user_123" } },
      );
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      from openai import OpenAI
      import os

      client = OpenAI(
          api_key=os.environ.get("ORQ_API_KEY"),
          base_url="https://api.orq.ai/v3/router",
      )

      response = client.chat.completions.create(
          model="openai/gpt-4o",
          messages=[{"role": "user", "content": "Hello"}],
          extra_headers={"X-ORQ-IDENTITY-ID": "user_123"},
      )
      ```
    </CodeGroup>
  </Tab>

  <Tab title="API Key Owner">
    When a request includes no `identity` body field and no `X-ORQ-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.
  </Tab>
</Tabs>

## Configuration

| Parameter      | Type      | Required | Description                                   | Constraints        |
| -------------- | --------- | -------- | --------------------------------------------- | ------------------ |
| `id`           | string    | Yes      | Unique identity identifier                    | Max 255 characters |
| `display_name` | string    | No       | Human-readable identity name                  |                    |
| `email`        | string    | No       | Identity email address                        |                    |
| `metadata`     | object\[] | No       | Array of objects with custom key-value pairs  | Max 20 fields      |
| `logo_url`     | string    | No       | URL to identity's profile image               |                    |
| `tags`         | string\[] | No       | Classification tags for identity segmentation | Max 10 tags        |

<Card title="Identities: manage, list, and view metrics" icon="user-tag" href="/docs/ai-studio/observability/identities">
  Covers creating identities via the dashboard or API, listing with 30-day usage metrics, and retrieving identity records.
</Card>