Skip to main content
Identities group AI Gateway requests by user, team, project, or client, giving per-identity visibility into cost, token usage, and error rates. They can represent:
  • a User
  • a Team
  • a Project
  • a Client
Identities list showing name, source tag, request count, cost in dollars, token count, and error rate columns.

​
Creating an identity

Create identities via the API or SDK before attaching them to requests. 
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": "Client A",
    "email": "[email protected]",
    "metadata": {
      "role": "admin"
    }
}'
See the API Reference for the full parameter specification.

​
Budget control

Set a spending budget on an identity to cap how much a user or team can spend within a period. When the identity’s spend reaches the limit, subsequent requests return 429 Too Many Requests until the period resets. Available periods: Daily, Weekly, Monthly, Yearly.
Identity budget panel showing a Daily budget of 0.20, 0.08 consumed (40%), with a circular progress indicator and a Reset button.

​
Attaching an identity to a request

Pass the identity’s external_id in the identity.id field on any AI Gateway request. If no identity with that external_id exists, one is created automatically. 
curl 'https://api.orq.ai/v3/router/chat/completions' \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "anthropic/claude-fable-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "identity": {"id": "user_123"}
  }'
To use the SDK instead, pass identity on each request:
The identityId / identity_id constructor option was removed in SDK v4.10.0. Pass identity on each request instead.
import { Orq } from "@orq-ai/node";

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

const response = await orq.responses.create({
  model: "anthropic/claude-fable-5",
  input: "Hello",
  identity: { id: "user_123" },
});

​
Retrieving an identity via the API

Once an identity is in use, fetch its full record at any time using its _id (ULID) or external_id. 
curl 'https://api.orq.ai/v2/identities/<id>' \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H 'Accept: application/json'
The response returns the full identity record: 
{
  "_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"
}
See the API Reference for the full parameter and response specification.

​
Listing identities with metrics

Pass include_metrics=true to retrieve 30-day usage metrics for each identity. 
curl 'https://api.orq.ai/v2/identities?include_metrics=true' \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H 'Accept: application/json'
Each identity includes a metrics object covering the last 30 days:
FieldDescription
total_costTotal spend in USD
total_tokensTotal tokens consumed
total_requestsTotal number of requests
error_rateRatio of failed requests (e.g. 0.33 = 33% errors)
See the API Reference for pagination, search, and tag filtering parameters.