Skip to content

AgentMarginDevelopers

Unknown costs

AgentMargin never reads a missing price as free usage. With no reported cost and no usable price at ingestion, an event's cost is marked unknown.

v0.3.0-alpha · experimentalLocalhost onlySource: docs/UNKNOWN_COSTS.md

What analytics returns

An authenticated GET /v1/analytics?start=…&end=… includes:

json
{
  "unknownModels": [
    { "model": "example-model", "eventCount": 4 }
  ],
  "unknownModelsTruncated": false
}
  • unknownModels lists up to 20 model names with the most unknown-cost events, ordered by count, then name.
  • unknownModelsTruncated: true means more than 20 distinct models are affected. The list isn't complete.
  • Queries always filter on the authenticated workspace and the selected UTC window.
  • Counts are events, not customers, invoices, dollars or an estimate of spend.
  • Model names are untrusted text. The dashboard never renders them as HTML.

What it does to margins

Unknown events suppress the final AI contribution and margin for the affected customers. Only known-cost events add to knownAiCostMicros.

When a model is listed

  1. Confirm the provider response actually contains usage and that the model identifier is mapped correctly.
  2. Prefer the provider's reported cost where it's trustworthy and available.
  3. Otherwise add an independently verified price version with the right effective dates. Watch cached-input rates when cached tokens are present.
  4. Retry only newly generated, distinct events. Existing event IDs and stored costs are immutable.