> ## Documentation Index > Fetch the complete documentation index at: https://sidenet.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Traces, cost and billing groups > What a trace records, how cost is attributed per message and per customer, and how margin is calculated. 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: | Field | What it says | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent and version | Which agent answered, as its version id. | | Model requested and served | The configured slug or `policy/…` alias, and — filled in after the stream — the concrete model that actually served, as `streamedModel`. | | Participants | The agents and tools that ran, each with a success flag; errors on tools. | | Tokens and cost | Input, output and total tokens; cost in dollars. | | Latency | Start to end of the turn. | | Environment | `dev`, `staging` or `prod` from the network that served it; `experiment` for experiment runs. | | Source | Whatever the client declared in its `X-Source` header — the SDK sends its version — and `workflow-schedule`, `workflow-run-now`, `workflow-manual` or `workflow-test` for workflow runs. | | Group | The billing group, both its stable id and its display name. | | Thread and message | Links to the conversation and the specific message, so a trace can be replayed. | | Request id | One per inbound request, shared by everything that request did. | 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. ```bash theme={null} curl -X PATCH https://api.sidenet.ai/v1/groups/acme \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corp", "monthly_limit": 250 }' ``` `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](/docs/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.