ARouter supports per-user usage tracking by passing a user field in your API requests. This lets you attribute API costs to individual users in your application and monitor usage patterns at the user level.
Passing a User ID
Include the user field in any chat completions request:
{
"model": "openai/gpt-5.4",
"messages": [{"role": "user", "content": "Hello!"}],
"user": "user_12345"
}
user value can be any string that identifies the end user in your system — a database ID, a hashed email, or a session ID. ARouter does not validate or interpret this value.
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.arouter.ai/v1",
apiKey: "lr_live_xxxx",
});
async function chatWithUser(userId: string, message: string) {
const response = await client.chat.completions.create({
model: "openai/gpt-5.4",
messages: [{ role: "user", content: message }],
user: userId,
});
return response.choices[0].message.content;
}
from openai import OpenAI
client = OpenAI(
base_url="https://api.arouter.ai/v1",
api_key="lr_live_xxxx",
)
def chat_with_user(user_id: str, message: str) -> str:
response = client.chat.completions.create(
model="openai/gpt-5.4",
messages=[{"role": "user", "content": message}],
user=user_id,
)
return response.choices[0].message.content
curl https://api.arouter.ai/v1/chat/completions \
-H "Authorization: Bearer lr_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.4",
"messages": [{"role": "user", "content": "Hello!"}],
"user": "user_12345"
}'
Privacy Considerations
Do not pass personally identifiable information (PII) as the user value. Use opaque identifiers such as hashed IDs or database primary keys.
import hashlib
# Hash the user's email before passing
user_id = hashlib.sha256(user_email.encode()).hexdigest()[:16]
# Or use an opaque database ID
user_id = str(user.id) # e.g. "usr_abc123"
Viewing Usage by User
User-level usage data is available in the Activity Export. Each record includes the user field you passed, allowing you to:
- Calculate per-user token consumption and cost
- Identify high-usage users for capacity planning
- Detect anomalous usage patterns or abuse
- Build usage-based billing for your end users
Activity Export API
Query usage records filtered by user:
curl "https://api.arouter.ai/v1/activity?user=user_12345&limit=100" \
-H "Authorization: Bearer lr_live_xxxx"
Use Cases
Per-User Cost Allocation
Track how much each of your customers costs to serve:
// Pass your customer ID
const response = await client.chat.completions.create({
model: "anthropic/claude-sonnet-4.6",
messages: conversation,
user: `customer_${customerId}`,
});
// Later: query activity export to get total cost per customer
Abuse Detection
Monitor for unusual usage patterns by user:
# Each user gets their own identifier
response = client.chat.completions.create(
model="openai/gpt-5.4",
messages=[{"role": "user", "content": user_message}],
user=f"app_user_{user.id}",
)
Multi-Tenant Applications
In multi-tenant SaaS applications, pass an organization or tenant ID:
const response = await client.chat.completions.create({
model: "google/gemini-2.5-flash",
messages: messages,
user: `org_${organizationId}`,
});
Notes
- The
user field is optional. Requests without it are still tracked under your API key’s aggregate usage.
- User IDs are stored as opaque strings. ARouter does not validate, parse, or interpret the format.
- User tracking data is included in Activity Export records.
- See Organization Management for team-level usage controls.
