> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Report Usage

Reports usage of a metered feature for a customer.

## Mutation

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation ReportUsage($input: ReportUsageInput!) {
    reportUsage(input: $input) {
      measurementId
      currentUsage
    }
  }
  ```

  ```json Variables theme={null}
  {
    "input": {
      "customerId": "customer-123",
      "featureId": "feature-api-calls",
      "value": 100
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "reportUsage": {
        "measurementId": "measure-789",
        "currentUsage": 4632
      }
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="input" type="ReportUsageInput" required>
  Input for reporting usage

  <Expandable title="properties">
    <ParamField body="customerId" type="String" required>
      Customer reference ID
    </ParamField>

    <ParamField body="featureId" type="String" required>
      Feature reference ID
    </ParamField>

    <ParamField body="value" type="Float" required>
      Usage value to report
    </ParamField>

    <ParamField body="resourceId" type="String">
      Resource ID for multi-resource
    </ParamField>

    <ParamField body="updateBehavior" type="UsageUpdateBehavior">
      `DELTA` (add to current) or `SET` (replace current)
    </ParamField>

    <ParamField body="createdAt" type="DateTime">
      Timestamp of when the usage was recorded
    </ParamField>

    <ParamField body="dimensions" type="JSON">
      Additional dimensions for the usage report
    </ParamField>

    <ParamField body="environmentId" type="UUID">
      Environment ID
    </ParamField>
  </Expandable>
</ParamField>

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

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "featureId": "feature-api-calls",
    "value": 100,
    "updateBehavior": "DELTA"
  }
}
```

### Set Absolute Value

```json theme={null}
{
  "input": {
    "customerId": "customer-123",
    "featureId": "feature-storage",
    "value": 5.5,
    "updateBehavior": "SET"
  }
}
```

## Common Use Cases

<AccordionGroup>
  <Accordion title="API call tracking">
    Report API calls as they happen for rate limiting.
  </Accordion>

  <Accordion title="Storage metering">
    Update storage usage periodically.
  </Accordion>

  <Accordion title="Event-based billing">
    Report usage events for billing calculation.
  </Accordion>
</AccordionGroup>

## Related Operations

* [Report Usage Bulk](/api-and-sdks/api-reference/mutations/report-usage-bulk) - Bulk reporting
* [Usage History](/api-and-sdks/api-reference/queries/usage-history) - Query history