Customers

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

You can attach a display name to a customer to make traces easier to identify in the observatory. Pass a customer object to set the ID and 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),
);

You can identify the customer in either of two ways — use one form or the other:

• Pass customer_id / customerId when you only need the ID.
• Pass a customer object when you also want to set a display name. The object contains id and can include name.

The same two options are available with turn(), a trace context, and the trace update helper. 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.

View Customers

Once your traces carry a customer ID, open Customers under Observe in the sidebar. The page shows every customer that sent a trace in the selected window, so you can see which accounts are thriving and which need attention.

Use the date picker, environment dropdown, and filters at the top to scope the whole page. The window defaults to the last three months.

Customer Overview

The top of the page summarizes your customer base for the selected window:

• Customers — active and new customers over time, with active users on a second axis. Drag across the chart to zoom the page into that range.
• Most active customers — customers ranked by trace count, alongside their total cost. Click a row to open that customer.
• Cost per customer — the average cost of a customer over the window.
• Sentiment — the share of negative sentiment over the window.
• Issues — the number of classified issues over the window.
• Retention — a cohort table. Each row is the customers first seen in a period, and each column shows how many of them came back that many periods later. Switch between daily, weekly, and monthly cohorts.

Customers Table

Below the overview, a table lists each customer with its name, sentiment split, top issue, number of users, traces, threads, cost, and last activity. It is sorted by negative sentiment share by default, so the customers with the highest share of negative sentiment come first.

Search by name or customer ID, sort by any column except the name, and use the column editor to choose which columns appear.

Customer Details

Click a customer to open its detail page. The cards at the top cover the same window as the page:

• Cost — total cost for this customer, with cost over time.
• Last seen — the most recent trace, when the customer was first seen, and a strip showing when in the window it was active.
• Sentiment — the breakdown of sentiment labels across this customer's interactions.
• Issues and Use Cases — the labels this customer hits most often.

Below the cards, the Users, Traces, and Threads tabs list the end users, traces, and threads that belong to this customer. Click the page title to rename the customer without changing your code.

Next Steps

Last updated on October 6, 2026