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

# Displaying Usage

> Show current usage totals and usage history to your customers for limit features.

Often, you'll need to show your customers how much usage they have available on your UI.

You can use our API to do this.

## Show current totals

Most usage information for a customer is available when you evaluate a customer's feature access via the [feature access endpoint](/api-reference/endpoint/feature-access).

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

  export function CreditsUsageCard() {
    const { usage, isUnlimited, limit, isLoading } = useFeatureAccess<MyFeatures>("credits");

    if (isLoading) return <div>Loading...</div>;
    if (!usage) return <div>No usage data available.</div>;

    const used = usage.used;
    const effectiveLimit = isUnlimited ? null : limit;
    const hasReachedLimit = usage.hasReachedLimit;
    const bonusRemaining = usage.bonusRemaining;
    const bonusUsed = usage.bonusUsed;
    const nextReset = usage.nextReset;
    const label = isUnlimited ? "Unlimited" : `${used} / ${effectiveLimit}`;

    return (
      <div>
        <p>Credits used: {label}</p>
        <p>Bonus remaining: {bonusRemaining}</p>
        <p>Bonus used: {bonusUsed}</p>
        <p>Limit reached: {hasReachedLimit ? "Yes" : "No"}</p>
        <p>Next reset: {nextReset ? new Date(nextReset).toLocaleString() : "N/A"}</p>
      </div>
    );
  }
  ```

  ```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 credits = await priceos.features.getAccess("customer_123", "credits");
  const used = credits.usage.used;
  const limit = credits.isUnlimited ? null : credits.limit;
  const hasReachedLimit = credits.usage.hasReachedLimit;
  const bonusRemaining = credits.usage.bonusRemaining;
  const bonusUsed = credits.usage.bonusUsed;
  const nextReset = credits.usage.nextReset;
  const label = credits.isUnlimited ? "Unlimited" : `${used} / ${limit}`;
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.priceos.com/v1/feature-access?customerId=customer_123" \
    -H "x-api-key: PRICEOS_API_KEY"
  ```
</CodeGroup>

## <Warning>The `limit` field is the base limit set in the feature. It does not include any bonuses.</Warning>

## Show usage history

If you want a list of all the usage events, then you can use our [list usage events endpoint](/api-reference/endpoint/usage-events).

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

  export function CreditsUsageHistory() {
    const { usageEvents, hasMore, getMore, isLoading } = useUsageEvents<MyFeatures>("credits", {
      period: "current",
      limit: 20,
    });

    if (isLoading) return <div>Loading...</div>;

    return (
      <div>
        <ul>
          {usageEvents.map((event) => (
            <li key={event.id}>
              {event.amount} at {new Date(event.occurredAt).toLocaleString()}
            </li>
          ))}
        </ul>
        {hasMore ? <button onClick={() => void getMore()}>Load more</button> : null}
      </div>
    );
  }
  ```

  ```ts TypeScript theme={null}
  const { usageEvents, hasMore } = await priceos.usage.listEvents({
    customerId: "customer_123",
    featureKey: "credits",
    period: "current",
    limit: 20,
    offset: 0,
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.priceos.com/v1/usage/events" \
    -H "x-api-key: PRICEOS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "customer_123",
      "featureKey": "credits",
      "period": "current",
      "limit": 20,
      "offset": 0
    }'
  ```
</CodeGroup>

You can pass `customRange` to fetch a specific time window. Provide either `customRange` or `period`, not both.