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

---

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