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 with their source, request count, cost, token usage, and error rate.

​
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 via the X-ORQ-IDENTITY-ID header on any AI Gateway request.
cURL
curl 'https://api.orq.ai/v3/router/chat/completions' \
  -H 'Authorization: Bearer $ORQ_API_KEY' \
  -H 'X-ORQ-IDENTITY-ID: user_123' \
  -H 'Content-Type: application/json' \
  -d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
Or initialise the SDK with an identity ID so every call in the session is attributed automatically: 
import { Orq } from "@orq-ai/node";

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

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