> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# User Tracking

> Track API usage by individual users in your application using the user field. Useful for per-user analytics, cost allocation, and abuse detection.

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:

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    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;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

***

## Privacy Considerations

<Warning>
  Do not pass personally identifiable information (PII) as the `user` value. Use opaque identifiers such as hashed IDs or database primary keys.
</Warning>

Recommended approaches:

```python theme={null}
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](/en/guides/administration/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:

```bash theme={null}
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:

```typescript theme={null}
// 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:

```python theme={null}
# 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:

```typescript theme={null}
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](/en/guides/administration/activity-export) records.
* See [Organization Management](/en/guides/administration/organization-management) for team-level usage controls.