> ## 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 through the API](/docs/analytics/identity#creating-an-identity-using-the-api) and then are used as supplementary data to store Identity Metrics within any other call of the API.

<img src="https://mintcdn.com/orqai/E8L3R46ivX7g9-QI/images/docs/d093a6874c287c0ea39febf83416fe8a6831f51ccabae0f88ea6e095ad4f102b-4293dd1-contacts.jpg?fit=max&auto=format&n=E8L3R46ivX7g9-QI&q=85&s=3157dc3a92a88ad84c1118df5d34b61a" alt="Identities list with their source, request count, cost, token usage, and error rate." width="1780" height="1082" data-path="images/docs/d093a6874c287c0ea39febf83416fe8a6831f51ccabae0f88ea6e095ad4f102b-4293dd1-contacts.jpg" />

## Creating an identity using the Studio

To create an Identity, head to the **Identity Analytics** 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" />

### Budget Control

When creating an identity, set a **Budget** in order to:

* Prevent individual users from exceeding the allocated AI budget
* Set department-level spending limits for the enterprise team
* Control costs across multiple AI models and services

Each budget has a **period** and an **amount** (in USD). When the identity's spend reaches the limit within the period, subsequent requests are blocked with a `429 Too Many Requests` response until the period resets.

The available periods are **Daily**, **Weekly**, **Monthly**, and **Yearly**.

<Frame caption="See the current spending of an identity by viewing their detail">
  <img src="https://mintcdn.com/orqai/mDs6v2JrTlXp9Ikl/images/docs/fcf5aff38411309481571a64888af08d6db0dcc9af2584b32abacbc7865f852e-image.png?fit=max&auto=format&n=mDs6v2JrTlXp9Ikl&q=85&s=bfa8263d20029ae5309a0a228881be14" alt="Identity budget panel showing a Daily budget of 0.20, 0.08 consumed (40%), with a circular progress indicator and a Reset button." width="2732" height="1184" data-path="images/docs/fcf5aff38411309481571a64888af08d6db0dcc9af2584b32abacbc7865f852e-image.png" />
</Frame>

## Creating an identity using the API

To create an identity, you have two options:

1. **Use the API directly**: You can create an Identity with the cURL code snippet.
2. **SDK Implementation**: (Recommended) The SDK provides a more streamlined approach to creating Identities.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}

  curl --location 'https://api.orq.ai/v2/identities' \
  --header 'Authorization: Bearer <your-api-key>:' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "external_id": "1234",
      "display_name": "Client A",
      "email": "[email protected]",
      "avatar_url": "https://gravatar.com/avatar/6c568aaa96fdbd3e466b500e6eb312dc?s=400&d=robohash&r=x",
      "metadata": {
        "role": "admin"
      }
  }'
  ```

  ```typescript Typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  try {
    const identity =client.identities.create({
      externalId: 'user123',
      displayName: 'John Doe',
      email: '[email protected]',
      metadata: { role: 'admin', department: 'IT' },
      avatarUrl: 'https://example.com/avatar.jpg',
    });
  } catch (e) {
    console.error(e);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  identity = client.identities.create(
      external_id="user123",
      display_name="John Doe",
      email="[email protected]",
      avatar_url="https://example.com/avatar.jpg",
      metadata={"role": "admin"}
  )
  ```
</CodeGroup>

<Info>
  Developers, please see the [API Reference](/reference/identities/create-an-identity) for further explanation.
</Info>

## Using Identity metrics

To track Identity metrics effectively, you have two primary options:

1. API Direct Usage: When using the API directly, you can attach the `identity ID` through the request headers.
2. SDK Implementation: We strongly recommend using our SDKs, as they provide a more streamlined approach to tracking identity metrics.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl 'https://api.orq.ai/v2/deployments/invoke' \
  -H 'Authorization: Bearer {apiKey}' \
  -H 'X-ORQ-IDENTITY-ID: <external_id>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
     "key": "<deployment_key>",
     "context": {
        "environments": []
     }
  }' \
  --compressed
  ```

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

  const client = new Orq({
    apiKey: 'orq-api-key',
    environment: 'production',
    // Optionally initiate the identityId for the session
    identityId: '<identityId>'
  });
  ```

  ```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", "__API_KEY__"),
      environment="production",
      identity_id="<identity_id>"
  )
  ```
</CodeGroup>

<Info>
  To learn more, see the [API Reference](/reference/identities/create-an-identity).
</Info>

## 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": "Jane Smith",
  "email": "[email protected]",
  "avatar_url": "https://example.com/avatars/jane-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": "Jane 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>