Cost Traces

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. 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?

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. Traces will group those events automatically once shipped.

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 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.

Add a trace key to your events

Include a stable identifier in event metadata so Macropay knows which events share a session.

Ingest events as usual

Keep emitting cost events the same way you do today — no separate API.

Query the trace

Retrieve the aggregated cost for a session, or analyze traces in the Dashboard alongside your other metrics.

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 (SDK)

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.

cURL

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"
      }
    }
  ]
}

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.

Where it fits

Cost Traces is the session layer on top of 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.

Cost Events

Attach a _cost to any event you ingest — the foundation traces build on

Cost Metrics

Query costs, profits, and customer lifetime value across your account

Bootup

Features

Integrate

Merchant of Record (MoR)

Why trace-level costs

How it will work

Example: costing one agent run

Where it fits

Cost Events

Cost Metrics

​Why trace-level costs

​How it will work

​Example: costing one agent run

​Where it fits

Cost Events

Cost Metrics

Why trace-level costs

How it will work

Example: costing one agent run

Where it fits