Report Usage

Reports usage of a metered feature for a customer.

Mutation

Mutation

mutation ReportUsage($input: ReportUsageInput!) {
  reportUsage(input: $input) {
    measurementId
    currentUsage
  }
}

Parameters

input · ReportUsageInput · required

Input for reporting usage

Show properties

customerId · String · required

Customer reference ID

featureId · String · required

Feature reference ID

value · Float · required

Usage value to report

resourceId · String

Resource ID for multi-resource

updateBehavior · UsageUpdateBehavior

DELTA (add to current) or SET (replace current)

createdAt · DateTime

Timestamp of when the usage was recorded

dimensions · JSON

Additional dimensions for the usage report

environmentId · UUID

Environment ID

Return Type

Returns a UsageMeasurementWithCurrentUsage with:

Field	Type	Description
measurementId	String	Measurement ID
currentUsage	Float	Updated current usage

Update Behaviors

Behavior	Description
DELTA	Add value to current usage (default)
SET	Set current usage to value

Examples

Increment Usage

{
  "input": {
    "customerId": "customer-123",
    "featureId": "feature-api-calls",
    "value": 100,
    "updateBehavior": "DELTA"
  }
}

Set Absolute Value

{
  "input": {
    "customerId": "customer-123",
    "featureId": "feature-storage",
    "value": 5.5,
    "updateBehavior": "SET"
  }
}

Common Use Cases

API call tracking

Report API calls as they happen for rate limiting.

Storage metering

Update storage usage periodically.

Event-based billing

Report usage events for billing calculation.

Related Operations

• Report Usage Bulk - Bulk reporting
• Usage History - Query history