> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporting calculated usage

## 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.

<Note>
  It is also possible to report usage in bulk using the [Report Usage Bulk](https://studio.apollographql.com/public/Stigg-API/variant/Production/schema/reference) endpoint in batches of 100 measurements (GraphQL SDK only; note the [rate limit](/api-and-sdks/integration/graphql/rate-limits) for this operation)
</Note>

## 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.

<Tip>
  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.
</Tip>

## Supported ingestion methods

<Tabs>
  <Tab title="REST API">
    <Card title="REST SDKs" href="/api-and-sdks/references/sdk/backend/rest/index" horizontal icon="code">
      Send usage data using REST SDKs available for TypeScript, Python, Go, Ruby, C#, and Java.
    </Card>

    <Card title="REST API: Report Usage" href="/api-and-sdks/api-reference/rest/usage-report" horizontal icon="server">
      Send calculated usage values via the REST API.
    </Card>
  </Tab>

  <Tab title="GraphQL">
    <Card title="Node.js: Reporting Usage" href="/api-and-sdks/integration/backend/nodejs#reporting-usage-measurements-to-stigg" horizontal>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <div
          style={{
        width: 28,
        height: 28,
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        flex: '0 0 28px',
      }}
        >
          <img
            src="https://mintcdn.com/stigg/RZ91VrR8WK9exrsp/images/docs/d96f126-Node.js_logo.svg?fit=max&auto=format&n=RZ91VrR8WK9exrsp&q=85&s=9b69b016f6c0715254fcc864d261f86f"
            alt="Node.js"
            width="28"
            height="28"
            style={{
          display: 'block',
          maxWidth: '100%',
          maxHeight: '100%',
          objectFit: 'contain',
        }}
            data-path="images/docs/d96f126-Node.js_logo.svg"
          />
        </div>

        <span>Send usage data with the Node.js SDK.</span>
      </div>
    </Card>

    <Card title="Python: Reporting Usage" href="/api-and-sdks/integration/backend/python#reporting-usage-measurements-to-stigg" horizontal>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <div
          style={{
        width: 28,
        height: 28,
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        flex: '0 0 28px',
      }}
        >
          <img
            src="https://mintcdn.com/stigg/FdQMosJ2Bzlx8vcI/images/docs/7469835-python-original.png?fit=max&auto=format&n=FdQMosJ2Bzlx8vcI&q=85&s=5aafc0be4f9d8245bec7a6910babe3bd"
            alt="Python"
            width="28"
            height="28"
            style={{
          display: 'block',
          maxWidth: '100%',
          maxHeight: '100%',
          objectFit: 'contain',
        }}
            data-path="images/docs/7469835-python-original.png"
          />
        </div>

        <span>Send usage data with the Python SDK.</span>
      </div>
    </Card>

    <Card title="Ruby: Reporting Usage" href="/api-and-sdks/integration/backend/ruby#reporting-usage-measurements-to-stigg" horizontal>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <div
          style={{
        width: 28,
        height: 28,
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        flex: '0 0 28px',
      }}
        >
          <img
            src="https://mintcdn.com/stigg/rbfzdbhZ6y5pB9n-/images/docs/9705d6b-ruby-original.png?fit=max&auto=format&n=rbfzdbhZ6y5pB9n-&q=85&s=06c498ccef5cf0868a1393dcc0a1ec77"
            alt="Ruby"
            width="28"
            height="28"
            style={{
          display: 'block',
          maxWidth: '100%',
          maxHeight: '100%',
          objectFit: 'contain',
        }}
            data-path="images/docs/9705d6b-ruby-original.png"
          />
        </div>

        <span>Send usage data with the Ruby SDK.</span>
      </div>
    </Card>

    <Card title="Go: Reporting Usage" href="/api-and-sdks/integration/backend/go#reporting-usage-measurements-to-stigg" horizontal>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <div
          style={{
        width: 28,
        height: 28,
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        flex: '0 0 28px',
      }}
        >
          <img
            src="https://mintcdn.com/stigg/zZAY_sXPTSVMcwio/images/docs/ccb79d0-go-original-wordmark.png?fit=max&auto=format&n=zZAY_sXPTSVMcwio&q=85&s=fca43821e3669faf1be1157cc5d235a8"
            alt="Go"
            width="28"
            height="28"
            style={{
          display: 'block',
          maxWidth: '100%',
          maxHeight: '100%',
          objectFit: 'contain',
        }}
            data-path="images/docs/ccb79d0-go-original-wordmark.png"
          />
        </div>

        <span>Send usage data with the Go SDK.</span>
      </div>
    </Card>

    <Card title="GraphQL: Reporting Usage" href="/api-and-sdks/integration/backend/graphql#reporting-usage-measurements-to-stigg" horizontal>
      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
        <div
          style={{
        width: 28,
        height: 28,
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
        flex: '0 0 28px',
      }}
        >
          <img
            src="https://mintcdn.com/stigg/fP4soQQ7PxwZeQ0V/images/docs/e088aed-image.png?fit=max&auto=format&n=fP4soQQ7PxwZeQ0V&q=85&s=07e5bfb75fc24b7916389b826ea73585"
            alt="GraphQL"
            width="28"
            height="28"
            style={{
          display: 'block',
          maxWidth: '100%',
          maxHeight: '100%',
          objectFit: 'contain',
        }}
            data-path="images/docs/e088aed-image.png"
          />
        </div>

        <span>Send usage data via the GraphQL API.</span>
      </div>
    </Card>
  </Tab>
</Tabs>

## 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.


## Related topics

- [Sidecar](/api-and-sdks/integration/backend/sidecar.md)
- [Reporting entitlement usage](/documentation/managing-customers-and-subscriptions/customers/reporting-entitlement-usage.md)
- [Metered features](/documentation/modeling-your-pricing-in-stigg/features/creating-features/metered-features.md)
- [Viewing usage events](/documentation/getting-usage-data-into-stigg/viewing-usage-events.md)
- [Usage, billing & credits](/api-and-sdks/integration/backend/usage-and-billing.md)