Ingest a usage event

post

https://api.tansohq.com/api/v1/client/events

Records a single usage event for billing and tracking. Events feed into invoice calculations for usage-based and hybrid plans.

Idempotency: Pass an eventIdempotencyKey to enable safe retries. If omitted, one is auto-generated. Duplicate keys return 409 Conflict.

Customer identification: Use customerReferenceId (your internal ID), stripeCustomerId (your Stripe customer ID), or customerId (Tanso UUID). Use one, not multiple.

Cost tracking: Optionally include costAmount to track provider costs (COGS) alongside usage. If omitted, Tanso calculates cost automatically using costInput (model + inputTokens/outputTokens for two-rate pricing) with fallback chain: account default cost config > global model pricing table.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

eventIdempotencyKey

string

A unique key for this event. Used to prevent duplicate processing on retries. Auto-generated if omitted.

eventName

string

required

Name of the event. Should match a feature key or a meaningful tracking label.

occurredAt

date-time

When the event occurred. ISO 8601 format. Defaults to the current time if omitted.

flowId

string

Optional flow identifier to correlate related events.

featureKey

string

The key of the feature this event tracks usage for. Used to resolve pricing rules and billing.

featureId

uuid

Feature UUID. If provided, supersedes featureKey.

customerReferenceId

string

Your internal customer ID. Use one of customerReferenceId, stripeCustomerId, or customerId.

stripeCustomerId

string

Stripe customer ID (cus_...). Creates a customer linked via Stripe bridge table. Preferred for Observe mode.

customerId

uuid

Tanso's internal customer UUID. Use one of customerReferenceId, stripeCustomerId, or customerId.

subscriptionId

uuid

Optional subscription ID to associate the event with a specific subscription.

entitlementId

uuid

Optional entitlement ID for direct entitlement attribution.

invoiceId

uuid

Optional invoice ID for direct invoice attribution.

costAmount

number

Provider cost (COGS) for this event. If omitted, Tanso calculates it automatically — either from costInput (model + provider lookup) or from the feature's configured cost model and usageUnits.

revenueAmount

number

What you charged your customer for this event. Used for margin analysis in Observe mode. If omitted and a pricing rule is configured, Tanso calculates it from usageUnits.

usageUnits

number

The quantity of usage to record (e.g., API calls, tokens, storage GB). Used for billing calculations and margin analysis.

costInput

object

Model and provider information for automatic cost calculation. When provided, Tanso looks up current provider pricing to calculate cost automatically. Use this instead of costAmount when you want Tanso to track costs based on the model you called. Pass inputTokens and outputTokens for accurate two-rate pricing (e.g., different rates for input vs output tokens).

200Event ingested, and the customer's usage has reached or exceeded the configured limit for this feature. The event is still recorded. Use the usageLimitExceeded flag to surface an upgrade prompt or restrict further access in your application.

201Event ingested successfully.

401Authentication failed. Verify your API key is correct and active.

403Access denied. Your API key does not have permission for this operation.

409Duplicate event detected. The event with this idempotency key has already been processed.