> ## 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.

# 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.

**Identities** are an entity used to tie metrics within the **orq.ai** 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.

<img src="https://mintcdn.com/orqai/zWQOppAHeVGc6aNz/images/identity-410.png?fit=max&auto=format&n=zWQOppAHeVGc6aNz&q=85&s=6401ddfdd8bb79a6eaca3a6919aff369" alt="Identities list showing name, source tag, request count, cost in dollars, token count, and error rate columns." width="1488" height="590" data-path="images/identity-410.png" />

## Creating an identity

<Tabs>
  <Tab title="AI Studio" icon="https://mintcdn.com/orqai/My16MDKJXrKALEHC/images/logos/ai-studio-round.svg?fit=max&auto=format&n=My16MDKJXrKALEHC&q=85&s=ac04dd509320d58ab9701cb6d6137733" width="100" height="100" data-path="images/logos/ai-studio-round.svg">
    Head to the **Identities** section and choose **Create an Identity**.

    The following panel opens:

    <img src="https://mintcdn.com/orqai/x_6IXnot9ETOc_0g/images/docs/57a6b1b53c879d1577786d064ca7d64b14b76c99ff7a2a1f759ba88d1e9bc622-image.png?fit=max&auto=format&n=x_6IXnot9ETOc_0g&q=85&s=cae3678fa171e7c92c76b7fae1c5e7fc" alt="Create identity form with fields for External ID, Display Name, Email, and a Budget toggle set to Monthly $10." width="556" height="399" data-path="images/docs/57a6b1b53c879d1577786d064ca7d64b14b76c99ff7a2a1f759ba88d1e9bc622-image.png" />
  </Tab>

  <Tab title="API / SDK" icon="code">
    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl --location 'https://api.orq.ai/v2/identities' \
      --header "Authorization: Bearer $ORQ_API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
          "external_id": "user_123",
          "display_name": "John Smith",
          "email": "john@acme.com",
          "metadata": {
            "role": "admin"
          }
      }'
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import { Orq } from "@orq-ai/node";

      const orq = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

      const identity = await orq.identities.create({
        externalId: "user_123",
        displayName: "John Smith",
        email: "john@acme.com",
        metadata: { role: "admin" },
      });
      ```

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

      orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

      identity = orq.identities.create(
          external_id="user_123",
          display_name="John Smith",
          email="john@acme.com",
          metadata={"role": "admin"},
      )
      ```
    </CodeGroup>

    <Info>
      See the [API Reference](/reference/identities/create-an-identity) for the full parameter specification.
    </Info>
  </Tab>
</Tabs>

## 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-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 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.
    </Note>

    **Agents**

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl 'https://api.orq.ai/v3/router/responses' \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H 'Content-Type: application/json' \
      --data-raw '{
        "model": "agent/my-agent",
        "input": "Hello",
        "identity": {"id": "<external_id>"}
      }'
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import { Orq } from "@orq-ai/node";

      const client = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

      const response = await client.responses.create({
        model: "agent/my-agent",
        input: "Hello",
        identity: { id: "<external_id>" },
      });
      ```

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

      client = Orq(api_key=os.environ.get("ORQ_API_KEY"))

      response = client.responses.create(
          model="agent/my-agent",
          input="Hello",
          identity={"id": "<external_id>"},
      )
      ```
    </CodeGroup>

    **Deployments**

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl 'https://api.orq.ai/v2/deployments/invoke' \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H 'Content-Type: application/json' \
      --data-raw '{
        "key": "<deployment_key>",
        "context": {"environments": ["production"]},
        "identity": {"id": "<external_id>"},
        "messages": [{"role": "user", "content": "Hello"}]
      }'
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import { Orq } from "@orq-ai/node";

      const client = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

      await client.deployments.invoke({
        key: "<deployment_key>",
        context: { environments: ["production"] },
        identity: { id: "<external_id>" },
        messages: [{ role: "user", content: "Hello" }],
      });
      ```

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

      client = Orq(api_key=os.environ.get("ORQ_API_KEY"))

      client.deployments.invoke(
          key="<deployment_key>",
          context={"environments": ["production"]},
          identity={"id": "<external_id>"},
          messages=[{"role": "user", "content": "Hello"}],
      )
      ```
    </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>

    **Agents**

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl 'https://api.orq.ai/v3/router/responses' \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "X-ORQ-IDENTITY-ID: user_123" \
      -H 'Content-Type: application/json' \
      --data-raw '{
        "model": "agent/my-agent",
        "input": "Hello"
      }'
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import { Orq } from "@orq-ai/node";

      const client = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

      const response = await client.responses.create(
        { model: "agent/my-agent", input: "Hello" },
        { headers: { "X-ORQ-IDENTITY-ID": "user_123" } },
      );
      ```

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

      client = Orq(api_key=os.environ.get("ORQ_API_KEY"))

      response = client.responses.create(
          model="agent/my-agent",
          input="Hello",
          http_headers={"X-ORQ-IDENTITY-ID": "user_123"},
      )
      ```
    </CodeGroup>

    **Deployments**

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl 'https://api.orq.ai/v2/deployments/invoke' \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "X-ORQ-IDENTITY-ID: user_123" \
      -H 'Content-Type: application/json' \
      --data-raw '{
        "key": "<deployment_key>",
        "context": {"environments": ["production"]},
        "messages": [{"role": "user", "content": "Hello"}]
      }'
      ```

      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import { Orq } from "@orq-ai/node";

      const client = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });

      await client.deployments.invoke(
        {
          key: "<deployment_key>",
          context: { environments: ["production"] },
          messages: [{ role: "user", content: "Hello" }],
        },
        { headers: { "X-ORQ-IDENTITY-ID": "user_123" } },
      );
      ```

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

      client = Orq(api_key=os.environ.get("ORQ_API_KEY"))

      client.deployments.invoke(
          key="<deployment_key>",
          context={"environments": ["production"]},
          messages=[{"role": "user", "content": "Hello"}],
          http_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>

## 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`.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request GET \
       --url https://api.orq.ai/v2/identities/<id> \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Bearer ORQ_API_KEY'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const identity = await orq.identities.retrieve({ id: "01ARZ3NDEKTSV4RRFFQ69G5FAV" });
    console.log(identity);
  }

  run();
  ```

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

  orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

  identity = orq.identities.retrieve(id="01ARZ3NDEKTSV4RRFFQ69G5FAV")
  print(identity)
  ```
</CodeGroup>

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": "[email protected]",
  "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"
}
```

<Info>
  See the [API Reference](/reference/identities/retrieve-an-identity) for the full parameter and response specification.
</Info>

## 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.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request GET \
       --url 'https://api.orq.ai/v2/identities?include_metrics=true' \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Bearer ORQ_API_KEY'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const identities = await orq.identities.list({ includeMetrics: true });

    console.log(identities.data);
    console.log('Has more:', identities.hasMore);
  }

  run();
  ```

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

  orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

  result = orq.identities.list(include_metrics=True)

  print(result.data)
  print(f"Has more: {result.has_more}")
  ```
</CodeGroup>

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": "[email protected]",
      "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) |

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