User Tracking

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"
}

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

TypeScript
Python
cURL

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.

Recommended approaches:

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.

Get Started

Core Concepts

Routing

Features

Guides

Privacy

Administration

Best Practices

Frameworks & Integrations

For Providers

Support

Passing a User ID

Privacy Considerations

Viewing Usage by User

Activity Export API

Use Cases

Per-User Cost Allocation

Abuse Detection

Multi-Tenant Applications

Notes

​Passing a User ID

​Privacy Considerations

​Viewing Usage by User

​Activity Export API

​Use Cases

​Per-User Cost Allocation

​Abuse Detection

​Multi-Tenant Applications

​Notes

Passing a User ID

Privacy Considerations

Viewing Usage by User

Activity Export API

Use Cases

Per-User Cost Allocation

Abuse Detection

Multi-Tenant Applications

Notes