---
title: "Report usage measurements"
method: POST
path: "/api/v1/usage"
tags: ["Usage"]
---

# Report usage measurements

`POST /api/v1/usage`

Reports usage measurements for metered features. The reported usage is used to track, limit, and bill customer consumption.

## Headers

- `X-ACCOUNT-ID` string
- `X-ENVIRONMENT-ID` string

## Request body

- ReportUsageRequestDto — Report usage for metered features. Batch up to 100 records.
  - `usages` object[], required — A list of usage reports to be submitted in bulk
    - `value` integer, required — The value to report for usage
    - `featureId` string, required — Feature id
    - `customerId` string, required — Customer id
    - `resourceId` string, nullable — Resource id
    - `createdAt` string, date-time — Timestamp of when the record was created
    - `updateBehavior` 'DELTA' | 'SET' — The method by which the usage value should be updated
    - `dimensions` object — Additional dimensions for the usage report
    - `idempotencyKey` string — Idempotency key

## Response `201`

The recorded usage measurement objects.

- UsageResponseDto — Response containing reported usage measurements with current usage values, period information, and reset dates for each measurement.
  - `data` object[], required — Array of usage measurements with current values and period info
    - `id` string, required — Unique identifier for the entity
    - `value` integer, required — The usage measurement record
    - `currentUsage` number, nullable — The current measured usage value
    - `credit` object, nullable — Optimistic credit balance for a credit-backed feature
      - `currencyId` string, required — The credit currency identifier
      - `currentUsage` number, required — The wallet's total consumed credits for this currency (optimistic — includes not-yet-reconciled usage), shared across every feature that draws on the currency. This is the running balance, not this call's deduction — see `consumed` for that.
      - `usageLimit` number, required — The total credits granted
      - `timestamp` string, date-time, required — The grant-version timestamp of this balance, used by the SDK for last-write-wins reconciliation
      - `usagePeriodEnd` string, date-time, nullable — End of the current credit grant period (when recurring credits reset), if applicable
      - `consumed` number, required — The credits this single reportUsage call deducted, in credit units — scoped to this one measurement (0 for idempotency duplicates). Contrast `currentUsage`, which is the wallet-wide running total shared across all features on this currency. Use it to reconcile expected per-call deductions.
    - `usagePeriodStart` string, date-time, nullable — The start date of the usage period in which this measurement resides (for entitlements with a reset period)
    - `usagePeriodEnd` string, date-time, nullable — The end date of the usage period in which this measurement resides (for entitlements with a reset period)
    - `nextResetDate` string, date-time, nullable — The date when the next usage reset will occur
    - `timestamp` string, date-time, required — Timestamp
    - `featureId` string, required — Feature id
    - `customerId` string, required — Customer id
    - `resourceId` string, nullable — Resource id
    - `createdAt` string, date-time, required — Timestamp of when the record was created

## Other responses

- `400` — bad request.
- `401` — User is not authenticated.
- `403` — User is not allowed to access this resource.
- `409` — Usage conflict error.
- `429` — Too many requests.

## Changes

- **2026-07-23** `b876edd1a4fc` — 5 warning, 1 info
  - added the new `CreditOveragePriceCurrencyNotFound` enum value to the `code` response property for the response status `400`
  - added the new `InvalidCreditOverageBillingModel` enum value to the `code` response property for the response status `400`
  - added the new `InvoicePreviewNotAvailableForDraftContract` enum value to the `code` response property for the response status `400`
  - added the new `OveragePriceNotSupportedOnAddon` enum value to the `code` response property for the response status `400`
  - …2 more
- **2026-07-12** `8b3d4ace525d` — 1 info
  - added the required property `data/items/credit/consumed` to the response with the `201` status
- **2026-07-08** `58bb216ff8ce` — 1 warning
  - added the new `GovernanceNotEnabled` enum value to the `code` response property for the response status `403`
- **2026-07-08** `a8a3b5df46c4` — 1 info
  - added the new optional request property `usages/items/idempotencyKey`
- **2026-06-23** `d7ea774f954e` — 1 info
  - added the optional property `data/items/credit/usagePeriodEnd` to the response with the `201` status

[Full history](https://skmtc.dev/stiggio/apis/stigg-api/changes/api/v1/usage/post.md)

---

[API](https://skmtc.dev/stiggio/apis/stigg-api.md) · [All operations](https://skmtc.dev/stiggio/apis/stigg-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stiggio/stigg-api/revisions/3e2c8cfcd035/schema)