Skip to main content
Deprecated: The “Contacts” feature has been deprecated in favor of Identities. If you’re currently using Contacts, please migrate to Identities for continued support and access to new features. See the API reference for implementation details.
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 through the API and then are used as supplementary data to store Identity Metrics within any other call of the API.

​
Creating an identity using the Studio

To create an Identity, head to the Identity Analytics section and choose Create an Identity. The following panel opens:

​
Budget Control

When creating an identity, set a Budget in order to:
  • Prevent individual users from exceeding the allocated AI budget
  • Set department-level spending limits for the enterprise team
  • Control costs across multiple AI models and services
Each budget has a period and an amount (in USD). When the identity’s spend reaches the limit within the period, subsequent requests are blocked with a 429 Too Many Requests response until the period resets. The available periods are Daily, Weekly, Monthly, and Yearly.

​
Creating an identity using the API

To create an identity, you have two options:
  1. Use the API directly: You can create an Identity with the cURL code snippet.
  2. SDK Implementation: (Recommended) The SDK provides a more streamlined approach to creating Identities.

curl --location 'https://api.orq.ai/v2/identities' \
--header 'Authorization: Bearer <your-api-key>:' \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_id": "1234",
    "display_name": "Client A",
    "email": "[email protected]",
    "avatar_url": "https://gravatar.com/avatar/6c568aaa96fdbd3e466b500e6eb312dc?s=400&d=robohash&r=x",
    "metadata": {
      "role": "admin"
    }
}'
Developers, please see the API Reference for further explanation.

​
Using Identity metrics

To track Identity metrics effectively, you have two primary options:
  1. API Direct Usage: When using the API directly, you can attach the identity ID through the request headers.
  2. SDK Implementation: We strongly recommend using our SDKs, as they provide a more streamlined approach to tracking identity metrics.
curl 'https://api.orq.ai/v2/deployments/invoke' \
-H 'Authorization: Bearer {apiKey}' \
-H 'X-ORQ-IDENTITY-ID: <external_id>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
   "key": "<deployment_key>",
   "context": {
      "environments": []
   }
}' \
--compressed
To learn more, see the API Reference.

​
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": "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 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": "Jane 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.