Reference

Usage and margin

What was called, what it cost you, and what was left over.

Two numbers are recorded for every call: what the provider charged you, and what you charged your customer. Everything on this page is those two, grouped differently.

Usage, by model name

cli

seams usage

# ROW    CALLS  IN TOKENS  OUT TOKENS  COST USD  CHARGED USD  MARGIN USD
# fast    2980    7781840     1160060     15.08        21.54        6.46
# smart   1625    4244640      632760      8.23        11.75        3.53
# cheap    813    2122320      316380      4.11         5.88        1.76

Field	Means
`group`	The row: a model name, an end user, or a day
`calls`	Requests that settled, successful or capped
`inputTokens` · `outputTokens`	As reported by the provider, not estimated
`providerCostMicros`	What the model provider charged you
`billedMicros`	What the end user was charged

Every money field is an integer count of micro-dollars, sent as a string. 1_000_000 micros is one dollar. Parse it as an integer; a float will eventually be a cent out and there is no rounding rule that saves you.

Margin, by end user

Margin answers the question a payment processor cannot: which customers are worth having. It knows revenue, and your provider invoice knows aggregate cost. Only the thing in the request path knows cost attributed to one person.

cli

seams margin --user alice --since 2026-08-01 --until 2026-09-01

Field	Means
`earningsMicros`	Recognised revenue from that end user
`providerCostMicros`	Attributed provider cost
`marginMicros`	The subtraction, which can be negative

A negative margin row is not an error. A customer on a flat monthly bundle who calls more than they pay for is exactly what these numbers exist to surface.

Filtering

Query	Narrows to
`endUserId`	One end user
`model`	One of your model names; usage only
`since` · `until`	An ISO 8601 instant each. `until` is exclusive
`groupBy`	`model`, `end-user` or `day`; usage only

Both operations return rows and totals. The totals are computed over the same filter, so a filtered total is the total of what you asked for rather than of everything.

Windows

Every analytics command takes the same window. The CLI reads a span as well as a date, so --since 30d and --since 2026-08-01 both work, and both reach the API as an instant. Give neither and you get the last 30 days.

cli

seams usage --since 30d --group-by day
seams margin --since 2026-08-01 --until 2026-09-01
seams requests --since 24h --limit 20