Group Users by Customer

Overview

Use customers to group end users that belong to the same account, organization, or tenant. Setting a customer on a trace lets you filter and compare activity, quality, usage, and cost by customer in Confident AI.

Customer IDs come from your application. They do not need to be domains or Confident AI organization IDs.

Set Customers at Runtime

Use a trace context when you know the customer before an auto-instrumented call starts:

from confident_trace import trace_context

def llm_app(query: str, customer_id: str):
    with trace_context(customer_id=customer_id):
        return agent.invoke(query)

import { traceContext } from "confident-trace";

const llmApp = (query: string, customerId: string) =>
  traceContext({ customerId }, () => agent.invoke(query));

Set Customer Fields

Use the customer_id / customerId shorthand when you only need the ID. Use the structured customer object to set an ID and display name together:

with trace_context(customer={"id": "customer-42", "name": "Acme Corp"}):
    return agent.invoke(query)

return traceContext(
  { customer: { id: "customer-42", name: "Acme Corp" } },
  () => agent.invoke(query),
);

Use one form or the other — the customer_id / customerId shorthand, or a customer object with id and name. Both fields are available on turn(), update_trace() / updateTrace(), and trace_context() / traceContext(). Python also accepts them when creating a span(); inside a TypeScript span() or withSpan() callback, call updateTrace().

Associate a User with a Customer

Set the customer and user on the same trace:

with trace_context(
    customer={"id": "customer-42", "name": "Acme Corp"},
    user={"id": "user-7", "name": "Marta"},
):
    agent.invoke(query)

The IDs should be stable identifiers from your application. Avoid putting secrets or credentials in IDs or names.

Next Steps

Last updated on September 23, 2026