Farther ShoreDocs
Go to Farther Shore
Getting startedCore conceptsLaunch checklist
ProductsUpstream routingEnvironmentsDeveloper portals
Billing strategiesPlans and limitsSubscribersAPI keys
Gateway enforcementUsage meteringLimits and creditsGateway sharding
Launch a request-counted product15mAdd monthly included usageAdd subscription plus overageCreate a prepaid credits productMeter AI token usageAdd a custom meterIssue and test an API keyDebug a denied requestUpdate product docsPrepare for launch
TroubleshootingGateway response codesMeter namingPlatform docs publishing
Status
Docs/Enforce & Meter/Usage metering

Usage metering

How usage events become billing and operational signals.

PreviousGateway enforcementNextLimits and credits

On this page

Event pathEstimated vs actual usageCommon metersBilling useOperational use

Usage metering turns gateway traffic into billable and operational data. It is how Farther Shore knows what a subscriber used, what to bill, and when a product is getting hot.

Event path

  1. Gateway receives a request.
  2. Gateway estimates usage before forwarding when needed.
  3. Upstream may report actual usage in response headers.
  4. Gateway reconciles estimated and actual usage.
  5. Gateway emits a usage event.
  6. Usage consumer batches events to core.
  7. Core aggregates usage for billing, analytics, limits, and autoscaling.

Estimated vs actual usage

Some products know usage before forwarding. A request-counted API can count one request immediately.

Other products only know usage after the upstream responds. AI APIs often learn actual token counts from the response.

Design product docs so subscribers understand when usage is counted and which unit appears on invoices.

Common meters

MeterMeaning
requestsOne billable API request.
input_tokensTokens sent into a model.
output_tokensTokens generated by a model.
dollarsCost expressed in currency units or micros.
creditsPrepaid balance spent by requests.
imagesGenerated or processed images.
storage_bytesStored data volume.

See Meter naming for naming guidance.

Billing use

Usage can power:

  • included usage counters
  • overage charges
  • pay-as-you-go billing
  • prepaid credit consumption
  • invoices and subscriber analytics

Operational use

Usage also powers operations:

  • detecting hot products
  • scaling gateway shards
  • identifying abuse
  • understanding product adoption
  • finding subscribers near limits

The same event stream can tell Farther Shore both what to bill and whether a product needs more gateway capacity.