---
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
    - `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-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`
- **2026-05-31** `0dece860f678` — 1 warning
  - added the new `DataExportIntegrationError` enum value to the `code` response property for the response status `400`
- **2026-05-28** `b181b166a2a5` — 1 warning
  - added the new `InvalidReceivedSignatureError` enum value to the `code` response property for the response status `400`

[Change 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/2ecdbf877f12/schema)