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

## 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 credits consumed (optimistic — includes not-yet-reconciled usage)
      - `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
    - `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-06-23** `d7ea774f954e` — 1 info
  - added the optional property `data/items/credit/usagePeriodEnd` to the response with the `201` status
- **2026-06-22** `6f80b1b6dd03` — 1 info
  - added the optional property `data/items/credit` to the response with the `201` status
- **2026-06-15** `7296f9e4b654` — 1 warning
  - added the new `InvoicePreviewNotAvailableForDraftContract` enum value to the `code` response property for the response status `409`
- **2026-06-08** `3acd63d6c861` — 2 info
  - added the new optional `header` request parameter `X-ACCOUNT-ID`
  - added the new optional `header` request parameter `X-ENVIRONMENT-ID`
- **2026-06-04** `4fa87d66426d` — 1 warning
  - added the new `PricingModelNotSupportedByBillingIntegration` enum value to the `code` response property for the response status `400`

[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/04d5fa9dcb6f/schema)