Track usage by identity

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.

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

Creating an identity

AI Studio
API / SDK

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.

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.

Get Started

AI Gateway

AI Observability

AI Engineering

AI Governance

AI Chat

Organization

Creating an identity

Attaching an identity to a request

Retrieving an identity via the API

Listing identities with metrics

​Creating an identity

​Attaching an identity to a request

​Retrieving an identity via the API

​Listing identities with metrics

Creating an identity

Attaching an identity to a request

Retrieving an identity via the API

Listing identities with metrics