/ai/v1), every request writes an ai.completion event carrying the billed amount (revenue) and the upstream provider cost (COGS). Macropay rolls those up into a MarginSummary — no metering code, no manual joins.
Revenue here is the amount you bill the end customer (the proxy’s marked-up
rate). Cost is what the upstream provider charged you. The difference is your
margin, sliced by model and flagged when it drops below a floor.
Where the numbers come from
Revenue & LLM cost
Each proxied call records billed amount and upstream model cost on the same
ai.completion event. Margin needs no extra reporting from you.Non-LLM COGS
Tool calls, third-party APIs, and human-in-the-loop time can be recorded as
agent.cost events that reduce margin — see below.Per-model breakdown
Every summary includes
by_model[], so you can see exactly which model is
eating your spread.Low-margin guardrail
A
low_margin flag trips the moment an agent’s margin falls under your
floor (default 20%), so thin or negative agents surface on their own.Read an agent’s margin
Two endpoints, sameMarginSummary shape. Both accept optional since and until ISO-8601 query params to scope a window.
Response: MarginSummary
The low-margin guardrail
low_margin is the single signal you alert on. It is true only when an agent has earned revenue and its margin_pct sits under margin_floor_pct — so an agent with no billed activity never trips it, and a profitable agent stays quiet. The floor defaults to 20%.
Wire it into monitoring: poll the org rollup on a schedule, and if low_margin is true or any entry in by_model[] shows a thin spread, you’ve caught a pricing or model-choice problem before it shows up on a P&L. A negative margin_cents means the agent is losing money on every run — usually a sign the upstream model costs more than you’re charging.
Record non-LLM costs
LLM spend is captured automatically, but agents also cost money in ways the proxy never sees: a paid search API, a geocoding lookup, a human reviewer. Report those as COGS withPOST /v1/agents/{id}/costs and they fold straight into the agent’s margin as an agent.cost event — adding cost without adding revenue.
A customer_id or external_customer_id is required so the cost attributes to the right account. Pass external_id as an idempotency key — it dedupes on (organization, external_id), so retries never double-count.
FAQ
How is margin calculated? Margin is billed revenue minus AI cost (COGS). Revenue and upstream model cost both come from theai.completion events the proxy records on every call; any agent.cost events you report add to the cost side. Macropay sums them into revenue_cents, cost_cents, and margin_cents, with margin_pct as margin over revenue. The breakdown per model lives in by_model[].
How do I record non-LLM costs?
Call POST /v1/agents/{id}/costs with amount_cents, a currency, an optional description, a customer_id or external_customer_id, and an external_id for idempotency. It’s stored as an agent.cost event that reduces margin without adding revenue. The SDK’s cost.record() wraps this endpoint.
What triggers the low-margin flag?
low_margin is true when an agent has earned revenue and its margin_pct is below margin_floor_pct (default 20%). An agent with no billed revenue never trips the flag, even if it has recorded costs.
Is margin a spending limit?
No. Margin is reporting only — it never blocks a request. To cap spend, set a budget limit on the proxy key in LLM inference; the proxy returns 403 once the ceiling is reached.
How does this relate to Cost Insights?
Agentic margin is the agent-scoped view of the same revenue-vs-cost ledger. For per-customer profit, LTV, and cost-annotated events beyond agents, see Cost Insights.
Next steps
Route calls through the AI proxy
Send model traffic through
/ai/v1 so revenue and cost are captured for you.Explore Cost Insights
See true profit, margin, and LTV per customer across your whole business.