Skip to main content
Every turn an assistant takes becomes a trace: who answered, what it called, what it cost. Every trace is attributed to a billing group — one of your customers, a team, a plan — and the Studio’s cost pages read from those traces alone. This page explains what is recorded, how the numbers are put together, and how to bill on them.

​
What a trace holds

A trace is a tree of spans rooted at the turn. The root carries: Routing has its own root span: the classifier’s model call is recorded and billed separately from the answer, tagged as the handoff agent. Memory, title generation and embeddings fold into the answer’s span.
Traces are the one source of truth. Cost on the traces page, on a group’s usage bar, in the margin tile and in a CSV export all come from summing the same root-span costs, so the dashboards agree with each other by construction.

​
How cost lands on a trace

Cost is not estimated from token counts. After each answer, and hourly as a safety net, a sweep asks the model gateway what each request actually cost and writes it onto the root span. The write is monotonic: spend that arrives late for a trace — a background task’s second turn, a delayed usage record — is picked up by the next sweep and added, never dropped, and re-running a sweep is a no-op when nothing changed. The consequence for you: a turn’s cost is normally visible moments after the answer, and a figure can grow slightly in the following minutes as late records land. Bill from a window that has closed, not from the last few minutes.

​
Billing groups

A group is the unit that spend attaches to — typically one of your customers. Every session, chat turn and workflow run names one. Use a stable id. Sessions and users take group_id; name the group once with PATCH /v1/groups/{groupId} or POST /v1/groups. Sending a display name without an id makes the name the match key, so “Acme”, “Acme Corp” and “ACME” become three groups and the same customer’s spend splits across them. An id never has that problem, and a changed name simply renames. Groups create themselves. An unseen group_id on a mint or a user update provisions the group with the default monthly cap. A session minted without any group bills to the user’s current group, then to the organization’s Default group — silently, so send it explicitly if you bill per team. Every group has a monthly limit. monthly_limit is enforced per calendar month against the sum of that group’s traces; null removes the cap. A group over its limit gets 429 on chat, workflow runs and experiments until the month rolls over or the cap is raised. The check is cached for ten seconds and fails open, so a transient database problem never blocks a customer.
GET /v1/groups?id=acme returns month_spend and limit_remaining alongside the cap, for showing a customer their own usage. In the Studio, each group’s usage bar turns amber at 70% of its cap and red at 90%. The organization itself has a lifetime credit balance; when spend across all groups reaches it, every request answers 429 until credits are added.

​
Margin

Each group has a margin percentage — what you charge that customer on top of model cost. The Studio’s cost page computes:
  • Gross margin — each group’s spend times its margin, summed.
  • Sidenet fee — the platform’s percentage of total spend, from your pricing plan.
  • Net margin — gross margin minus the fee. It can go negative when margins are set below the fee.
Margins are per group, so an enterprise customer and a free tier can carry different rates on the same platform account.

​
Evaluation spend

LLM judges used by experiments and trace scoring bill to a dedicated LLM Judges group per organization, with its own cap. It never appears in a customer’s usage, and it is excluded from the group listing.

​
The traces page

The Studio lists one row per turn — root spans only, with the routing classifier’s spans folded out of the list — for a date range that defaults to the last 30 days, with presets from today to year-to-date. Filters are added on demand and apply server-side across pages:
  • Environment — Dev, Staging, Prod.
  • Group — by billing group.
  • Agent — the agent that streamed the answer, all versions collapsed into one option.
  • Model — the model that actually served, which is how you find the turns a routing policy sent to a fallback.
Filter options are scoped to what is in the current window, so a model that served nothing last week is not offered when you are looking at last week. Each row shows the participants, errors, latency, tokens, cost, the user’s rating and comment if they voted, any scores, and a thread badge. Clicking the badge replays the conversation read-only, exactly as the user saw it — components rendered, routing shown — which is the fastest way from “this cost more than expected” to “here is the tool call that did it”.

​
Exports

Export writes the filtered rows to CSV, up to 50,000, with the columns in display order: timestamp, network and environment, group, streamed agent and model, participants, error count, latency, tokens, cost, scorers, rating, user id with thread id, input and output. Tokens and cost are separate numeric columns, so a monthly invoice per group is a pivot away. For programmatic billing, GET /v1/groups with month_spend is the lighter-weight call; the CSV is for reconciliation and audits.