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

# Track Usage

### Tracking Usage

To monitor customer usage and enforce limits or billing, record each usage event with Metrifox.

Send Usage Events

Use the `RecordUsage` method to log consumable feature usage, such as AI image generations or API calls. You always record usage in **feature units** (e.g. number of API calls) — never in credits.

<Note>
  Credits are never recorded or deducted directly. A feature is **credit-based** when it is priced as **prepaid** with a credit cost (e.g. 1 API call = 0.02 credits). When you record usage for that feature, Metrifox adds to the consumed count **and** automatically deducts the equivalent credits from the wallet funding it (4 API calls → `0.08` credits deducted).
</Note>

<Tip>
  Before recording usage, it’s best to verify that the customer is entitled to use the feature. This helps prevent:

  * Exceeding usage limits
  * Unauthorized access
  * Unintended overage charge
</Tip>

Each time a customer uses a feature:

1. Call the`RecordUsage`
2. Include relevant metadata (e.g. feature Key, quantity, timestamp)
3. Metrifox updates the customer’s usage balance accordingly

This ensures accurate enforcement of quotas, overage billing, and usage-based pricing.

<Card title="SDK available in" icon="file-code" horizontal href="https://docs.metrifox.com/api-reference/usage/record-usage">
  Javascript | Ruby | cURL | Python | PHP | Go | Java
</Card>

```json theme={null}
{
  "message": "Usage recorded",
  "event_name": "candidate.sourced",
  "customer_key": "cust-6d11ca90",
  "amount": 2
}
```

## Correcting a Recorded Event

Recorded an event that was wrong? Correct it with **`POST /usage/events/adjust`** using the original
`event_id`. Send the **actual** amount the customer used — sending the same value again is a safe no-op.

**Used less — refund the difference** (recorded 5, actually used 4):

```bash theme={null}
curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "customer_key": "cust-6d11ca90", "event_id": "evt_12345", "actual_quantity": 4 }'
```

**Used more — charge the difference** (recorded 200 credits, actually used 250):

```bash theme={null}
curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "customer_key": "cust-6d11ca90", "event_id": "evt_12345", "actual_credit_used": 250 }'
```

**Undo it** — leave the amounts out:

```bash theme={null}
curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "customer_key": "cust-6d11ca90", "event_id": "evt_12345" }'
```

See [Adjust a Usage Event](/api-reference/usage/adjust-usage) for details.

## **Adjusting Usage Counts for Persistent Features**

For **persistent-use features** — features that represent a standing count rather than one-off consumption, such as seats or licenses — you can **decrement the recorded usage count** by sending a **negative value** with `RecordUsage`.

This only applies to persistent features. It does not apply to consumable/event-style usage, and it does **not** add credits to a customer.

Use Case: Reclaiming Seats

If a customer is using 8 seats and removes one, send a quantity of `-1`. Metrifox updates their usage count from `used: 8` to `used: 7`, which frees up their available allowance for that feature (`available = allowance − used`).

<Note>
  This adjusts the **usage count** of a persistent feature only. To add **credits** to a customer, use a [credit topup](/api-reference/subscriptions/topup-credits) — recording negative usage does **not** add credits.
</Note>