Skip to main content
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

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.

​
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:
OrderSourceEffect
1identity object in the request bodyTags the request and upserts the identity record (name, email, metadata)
2X-ORQ-IDENTITY-ID request headerTags the request only; does not update the identity record
3API key ownerTags the request only; applies automatically when the key is user-owned
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>"}
}'
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"}]
}'

​
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'
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'
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
}
FieldDescription
total_costTotal spend in USD over the last 30 days
total_tokensTotal tokens consumed over the last 30 days
total_requestsTotal number of requests made over the last 30 days
error_rateRatio 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.