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

# Tracking Usage

> Record usage events for tracked limit features.

If you would like to use PriceOS to track customers' usage for your limit features, you can do so with our [track usage endpoint](/api-reference/endpoint/usage).

<Tip>
  See [creating limit features](/creating-features#limit-features) to learn how to set up usage tracking for features.
</Tip>

## Track a single usage event

<CodeGroup>
  ```tsx React theme={null}
  import { useTrackUsage } from "priceos/react";
  import type { MyFeatures } from "./priceos.types";

  export function TrackApiCallButton() {
    const { trackUsage } = useTrackUsage<MyFeatures>();

    async function onClick() {
      await trackUsage({
        featureKey: "api_calls",
        amount: 1,
        eventKey: "api_calls_customer_123_req_9f3a2",
      });
    }

    return <button onClick={onClick}>Record API call</button>;
  }
  ```

  ```ts Node.js theme={null}
  import { PriceOS } from "priceos";
  import type { MyFeatures } from "./priceos.types";

  const priceos = new PriceOS<MyFeatures>(process.env.PRICEOS_API_KEY!);

  const result = await priceos.usage.track({
    customerId: "customer_123",
    featureKey: "api_calls",
    amount: 1,
    eventKey: "api_calls_customer_123_req_9f3a2",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.priceos.com/v1/usage" \
    -H "x-api-key: PRICEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "customer_123",
      "featureKey": "api_calls",
      "amount": 1,
      "eventKey": "api_calls_customer_123_req_9f3a2"
    }'
  ```
</CodeGroup>

<Tip>
  You can use negative numbers in the amount field to reduce usage in our backend SDK and API only (not client side).
</Tip>

<Warning>
  `eventKey` is optional, but strongly recommended to deduplicate events and safely retry requests.
</Warning>

For more details, see [Track usage](/api-reference/endpoint/usage).

***

## Setting usage directly

Sometimes you just want to set usage totals directly instead of adding separate usage events.

You can use the [set usage](/api-reference/endpoint/usage-set) endpoint which will automatically calculate the usage event needed to get to your desired total.

<CodeGroup>
  ```ts Node.js theme={null}
  import { PriceOS } from "priceos";
  import type { MyFeatures } from "./priceos.types";

  const priceos = new PriceOS<MyFeatures>(process.env.PRICEOS_API_KEY!);

  const result = await priceos.usage.set({
    customerId: "customer_123",
    featureKey: "api_calls",
    used: 1200,
    eventKey: "set_usage_customer_123_api_calls_2026_02_18",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.priceos.com/v1/usage/set" \
    -H "x-api-key: PRICEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "customer_123",
      "featureKey": "api_calls",
      "used": 1200,
      "eventKey": "set_usage_customer_123_api_calls_2026_02_18"
    }'
  ```
</CodeGroup>

For more details, see [Set usage](/api-reference/endpoint/usage-set).

***

## Track usage in batch

Use batch when you need to send multiple events together (up to 100 per request).

<CodeGroup>
  ```ts Node.js theme={null}
  import { PriceOS } from "priceos";
  import type { MyFeatures } from "./priceos.types";

  const priceos = new PriceOS<MyFeatures>(process.env.PRICEOS_API_KEY!);

  const result = await priceos.usage.trackBatch({
    events: [
      {
        customerId: "customer_123",
        featureKey: "api_calls",
        amount: 1.5,
        eventKey: "evt_1",
      },
      {
        customerId: "customer_123",
        featureKey: "api_calls",
        amount: 2,
        eventKey: "evt_2",
      },
    ],
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.priceos.com/v1/usage/batch" \
    -H "x-api-key: PRICEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "events": [
        {
          "customerId": "customer_123",
          "featureKey": "api_calls",
          "amount": 1.5,
          "eventKey": "evt_1"
        },
        {
          "customerId": "customer_123",
          "featureKey": "api_calls",
          "amount": 2,
          "eventKey": "evt_2"
        }
      ]
    }'
  ```
</CodeGroup>

For more details, see [Track usage batch](/api-reference/endpoint/usage-batch).