Skip to main content

​
Overview

When calculated usage is reported to Stigg, your application is responsible for aggregating and calculating the usage and then reporting it to Stigg.

​
Supported ingestion behaviors

Stigg supports 2 behaviors for reporting calculated usage:
  1. Delta - the reported usage represents the change in usage of the feature, for example: when a customer adds 2 more seats, the reported value should be 2. This is default behavior.
  2. Set - the reported usage represents the end state after the change, for example: when a customer adds 2 more seats and the total number of seats after the change is 5, the reported value should be 5.
It is also possible to report usage in bulk using the Report Usage Bulk endpoint in batches of 100 measurements (GraphQL SDK only; note the rate limit for this operation)

​
Idempotency

Reporting usage over the network means requests can occasionally be retried, for example: after a timeout, a dropped connection, or a client-side retry policy. To make retries safe, you can pass an optional idempotencyKey alongside a reported usage value. Reports with a previously-seen idempotency key are deduplicated for 7 days; a retry with the same key inside that window is not double-counted. After the 7-day window, a report with the same key is treated as new usage, so idempotency keys shouldn’t be reused across unrelated reports.
Since calculated usage typically represents a delta (for example: “add 2 seats”), a duplicate that isn’t deduplicated is applied again and silently inflates the customer’s usage. Always pass an idempotencyKey when there’s a chance a report could be retried, such as usage reported from a background job or in response to a webhook.

​
Supported ingestion methods

REST SDKs

Send usage data using REST SDKs available for TypeScript, Python, Go, Ruby, C#, and Java.

REST API: Report Usage

Send calculated usage values via the REST API.

​
Example use-case

​
Seats

When a customer invites additional users to their environment, report the number of new seats that were added to Stigg. Similarly, when a customer removes users from their environment report the number of seats that were removed from the environment to Stigg.

​
Bandwidth

Periodically query the infrastructure that tracks used bandwidth (for example: AWS CloudWatch) and report the calculated usage to Stigg.