> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost Traces

> Roll up per-event costs into sessions to see the true cost of every agent run, conversation, or workflow

A single LLM call rarely tells the whole story. One customer request might fan out into a dozen model calls, a few tool invocations, and some retries — each one its own [cost event](/features/cost-insights/cost-events). **Cost Traces** stitches those events back together along a session boundary you define, so you can answer the question that actually matters: *what did this run cost me?*

<Note>
  Cost Traces is on the roadmap and not yet available. Today you can already
  attach a `_cost` to every event you ingest — see
  [Cost Events](/features/cost-insights/cost-events). Traces will group those
  events automatically once shipped.
</Note>

## Why trace-level costs

Per-event costs are precise but granular. To reason about margin, you usually want the cost of a *unit of work* — an agent task, a chat conversation, a checkout flow — not each underlying token call.

Cost Traces will let you:

* **Group events into sessions** using a trace key you control (a conversation ID, a job ID, an agent run ID).
* **See the fully-loaded cost** of each session: model spend, tool calls, and retries rolled into one number.
* **Compare cost to value.** Pair a session's cost (COGS) with the revenue or [agentic outcome](/features/cost-insights/cost-events) it produced to get true per-run margin.

This is the cost side of the agentic-margin picture: Macropay already tracks billed revenue per agent — Cost Traces closes the loop on what that revenue cost to deliver.

## How it will work

The model is intentionally simple: tag the events that belong together, and Macropay aggregates them into a trace.

<Steps>
  <Step title="Add a trace key to your events">
    Include a stable identifier in event metadata so Macropay knows which events
    share a session.
  </Step>

  <Step title="Ingest events as usual">
    Keep emitting [cost events](/features/cost-insights/cost-events) the same way
    you do today — no separate API.
  </Step>

  <Step title="Query the trace">
    Retrieve the aggregated cost for a session, or analyze traces in the
    Dashboard alongside your other [metrics](/features/analytics).
  </Step>
</Steps>

### Example: costing one agent run

Imagine a support agent that resolves a ticket across several model calls and a knowledge-base lookup. Tag each event with the same `_trace` so they roll up into one session:

```typescript icon="square-js" TypeScript (SDK) theme={null}
import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN,
});

const traceId = "ticket_7841"; // the unit of work you want to cost

await macropay.events.ingest({
  events: [
    {
      name: "llm.inference",
      externalCustomerId: "user_123",
      metadata: {
        _cost: { amount: 0.18, currency: "usd" }, // $0.0018
        _trace: traceId,
        step: "classify",
      },
    },
    {
      name: "kb.lookup",
      externalCustomerId: "user_123",
      metadata: {
        _cost: { amount: 0.02, currency: "usd" }, // $0.0002
        _trace: traceId,
        step: "retrieve",
      },
    },
    {
      name: "llm.inference",
      externalCustomerId: "user_123",
      metadata: {
        _cost: { amount: 0.41, currency: "usd" }, // $0.0041
        _trace: traceId,
        step: "draft_reply",
      },
    },
  ],
});
```

Once Cost Traces is live, those three events aggregate into a single session for `ticket_7841` — total cost **\$0.0061** — instead of three disconnected line items.

```json cURL theme={null}
POST https://api.macropay.ai/v1/events/ingest
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "events": [
    {
      "name": "llm.inference",
      "external_customer_id": "user_123",
      "metadata": {
        "_cost": { "amount": 0.18, "currency": "usd" },
        "_trace": "ticket_7841",
        "step": "classify"
      }
    }
  ]
}
```

<Tip>
  Pick a trace key at the boundary you bill or report on. For a chat product
  that's the conversation; for an agent platform it's the run; for a workflow
  engine it's the job. Whatever you choose, keep it stable across every event in
  the session.
</Tip>

## Where it fits

Cost Traces is the session layer on top of [Cost Events](/features/cost-insights/cost-events). Costs still ride along in event metadata; traces just give them shape. And because Macropay is your merchant of record — remitting sales tax and VAT worldwide so you don't carry that liability — the cost numbers you see here are your real cost of goods, cleanly separated from the tax and fees we handle on your behalf.

<CardGroup cols={2}>
  <Card title="Cost Events" icon="chart-line" href="/features/cost-insights/cost-events">
    Attach a `_cost` to any event you ingest — the foundation traces build on
  </Card>

  <Card title="Cost Metrics" icon="chart-bar" href="/features/analytics">
    Query costs, profits, and customer lifetime value across your account
  </Card>
</CardGroup>