Track usage by identity

Identities are entities 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.

Identities list showing name, source tag, request count, cost in dollars, token count, and error rate columns.

For the full set of ways to attach context to a request, including app name, threads, and custom metadata, see Request Metadata.

Creating an identity

AI Studio
API / SDK
CLI

Head to the Identities section and choose Create an Identity.The following panel opens:

Create identity form with fields for External ID, Display Name, Email, and a Budget toggle set to Monthly $10.

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

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" },
});

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"},
)

See the API Reference for the full parameter specification.

Create an identity using orq identities create:

orq identities create \
  --external-id user_123 \
  --display-name "John Smith" \
  --email john@acme.com \
  --metadata '{"role": "admin"}'

See install and setup to get started with the CLI. Run orq identities create --help for the full flag reference.

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

Body
X-ORQ-IDENTITY-ID Header
API Key Owner

Pass an identity object on each Agent response or Deployment invocation to attribute the request to an Identity.

The identityId / identity_id constructor option was removed in SDK v4.10.0. Pass identity on each request instead.

Agents

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

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>" },
});

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>"},
)

Deployments

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

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" }],
});

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"}],
)

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.

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.

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 endpoint, the request is processed but the tag is not attributed to any identity record.

Agents

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

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" } },
);

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"},
)

Deployments

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

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" } },
);

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"},
)

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.

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.

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'

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();

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)

The response returns the full identity record:

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

See the API Reference 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.

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'

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();

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

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

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

See the API Reference 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 for the full list of configurable limits, reset periods, and alerts.

Identity field reference

Fields accepted on the identity object for any 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
`metadata`	object[]	No	Array of objects with custom key-value pairs (max 20 fields)
`logo_url`	string	No	URL to a profile image
`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

Overview

Instrument your app

Explore

Monitor

Export

Review

Creating an identity

Attaching an identity to a request

Retrieving an identity via the API

Listing identities with metrics

Budget control

Identity field reference

Best practices

Troubleshooting

​Creating an identity

​Attaching an identity to a request

​Retrieving an identity via the API

​Listing identities with metrics

​Budget control

​Identity field reference

​Best practices

​Troubleshooting

Creating an identity

Attaching an identity to a request

Retrieving an identity via the API

Listing identities with metrics

Budget control

Identity field reference

Best practices

Troubleshooting