API Consumers (the `user` field)
Plan per-consumer tracking with the user request field. nRouter does not record the field yet, so the API Consumers page stays empty for now.
The API Consumers console (/[organization]/advanced-analytics/api-consumers) provides granular usage attribution, rate limiting, and spend tracking for downstream clients via the top-level user request parameter. Consumers populate automatically when passing user on inference calls, or can be pre-registered with dedicated limits via POST /api/end-users/create.
Telemetry Rollout Notice: While passing the
userfield in inference requests is fully supported, automatic aggregation in the API Consumers dashboard view is currently rolling out. Pre-registration endpoints and limit enforcement structures operate as documented below.
Consumer Identification
Pass a top-level user parameter in inference payloads:
curl -s https://api.nrouter.ai/v1/chat/completions \
-H "Authorization: Bearer sk-nrouter-<your-key>" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.5-flash",
"messages": [{"role": "user", "content": "hello"}],
"user": "u_8f3a1b9c"
}'Formatting Patterns
| Pattern | Example Value | Target Architecture | Granularity |
|---|---|---|---|
| End-User ID | u_8f3a1b9c | B2C apps tracking per-user consumption | 1 row per user |
| Tenant / Workspace | tenant_acme | B2B SaaS enforcing customer quotas | 1 row per tenant |
| Project / Service | proj_chatbot | Microservices tracking internal costs | 1 row per product |
| Composite Key | tenant_acme:u_8f3a1b9c | Hierarchical tenant and user tracking | Rows = tenants × users |
Privacy Best Practice: Always pass opaque, pseudonymous IDs (such as UUIDs or hashes); never send PII.
Management Workflows
- Pre-Registration: Provision limits before traffic via
POST /api/end-users/createor bulk viaPOST /api/end-users/bulk. - Metadata Tags: Attach labels (
plan:pro,region:eu) viaPOST /api/end-users/tagsfor display filtering (tags do not enforce limits). - Overrides: Set consumer-specific
rpm_limit,tpm_limit, andmax_budgetviaPUT /api/end-users/overrides(tightest limit among key, team, and consumer wins). - Audit Logging: Configuration changes are recorded in the organization audit trail at
/[organization]/audit.
API Endpoints
| Method & Path | Operation | Required Role |
|---|---|---|
POST /api/end-users/create | Pre-register a consumer | Owner / Org Admin |
POST /api/end-users/bulk | Bulk import consumers | Owner / Org Admin |
GET /api/end-users/tags?organization_id=<uuid>[&end_user_id=<str>] | List consumer tags | Member |
POST /api/end-users/tags | Attach consumer tag | Member (excl. Viewer) |
DELETE /api/end-users/tags?id=<uuid>&organization_id=<uuid> | Remove consumer tag | Member (excl. Viewer) |
GET /api/end-users/overrides?organization_id=<uuid> | Retrieve limit overrides | Member |
PUT /api/end-users/overrides | Upsert limits and budgets | Owner / Org Admin |
Parameters: user (max 200 chars), tag (max 60 chars), notes (max 500 chars). Table view paginates at 25 consumers per page.
Frequently asked questions
Do I need a mapping table on my side?
Optional: keep PII mappings in your own database and send only opaque IDs to nRouter.
Can I rename a consumer?
No, the user string is the identity, and changing it creates a new consumer record.
Does the field count against my budget?
No, the user field is an attribution parameter that carries no extra cost.
Is the field forwarded to the model provider?
Yes, OpenAI and other upstream providers receive the parameter in their native formats.
What if I send no user value at all?
The request succeeds and is billed normally without consumer attribution.
Why is my consumer's spend zero in the chart but non-zero in the table?
Charts show current billing cycle spend, while tables reflect lifetime cumulative volume.
Can a tag block a request?
No, tags are display labels only; hard caps are enforced via rate limit and budget overrides.
Where to go next
- API Key Management — Manage virtual keys and allowlists
- Team Management — Organize teams and department limits
- Budget Controls — Configure spend limits and rate controls