Concepts · Costs

Costs

Cost tracking in Esy separates estimates from provider-confirmed billing. Every cost has a source, a calculation method, and a confidence state — at the step, run, workflow, project, and organization level.

Estimates are not billing

Runtime responses include estimated costs immediately so operators can plan budgets, but provider-reported and reconciled costs are tracked separately. Final billing comes from provider truth, not Esy estimates.

Cost states

State	Meaning
`estimated`	Computed from Esy pricing snapshots and captured request settings.
`provider_reported`	Reported directly by a provider response or usage API.
`reconciled`	Matched against provider billing or usage records.
`disputed`	Internal estimate and provider-reported cost diverge beyond tolerance.

Provider cost ledger

Every provider interaction creates a ledger entry. Run telemetry rolls up these entries into a run-level totalCosts object with the same status semantics; project and organization burn roll up from runs.

provider_cost_ledger entryjson

{
  "provider": "fal.ai",
  "providerOperation": "background.remove",
  "model": "birefnet-light",
  "quantity": 1,
  "unit": "request",
  "unitPriceUsd": 0.0003,
  "estimatedCostUsd": 0.0003,
  "actualCostUsd": null,
  "status": "estimated",
  "pricingSource": "pricing_snapshot",
  "pricingVersion": "2026.05.16",
  "sourceUrl": "https://fal.ai/models/fal-ai/birefnet-light"
}

Pricing sources

Provider	Source of truth
fal.ai	Provider usage API for actuals; pricing snapshot for estimates while a run is in-flight.
openai	Documented pricing snapshot per model and quality, keyed to a dated pricingVersion.
storage (R2)	Per-operation pricing from Cloudflare; reconciled monthly via usage export.