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

# useUsageEvents

> List usage events from React with built-in pagination.

The `useUsageEvents` hook lists usage events for a single feature using your backend route.
By default it calls `GET /api/priceos/v1/usage-events` and requests the current period.

<Tip>
  Setup first: see the [React integration guide](/react-integration).
</Tip>

<Tabs>
  <Tab title="Typed">
    ```tsx theme={null}
    const result = useUsageEvents<MyFeatures>("api_calls", options?)
    ```
  </Tab>

  <Tab title="Untyped">
    ```tsx theme={null}
    const result = useUsageEvents("api_calls", options?)
    ```
  </Tab>
</Tabs>

## Parameters

<ParamField path="featureKey" type="string" required>
  Feature key to list events for (typed to your tracked limit feature keys when using generated types).
</ParamField>

<ParamField path="options.enabled" type="boolean">
  Enable or disable fetching. Defaults to `true`.
</ParamField>

<ParamField path="options.period" type="&#x22;current&#x22; | &#x22;previous&#x22;">
  Usage period to query. Defaults to `"current"`.
  Ignored when `customRange` is provided.
</ParamField>

<ParamField path="options.customRange" type="{ start: number; end: number }">
  Optional custom Unix-ms range. `start` and `end` are required when provided.
</ParamField>

<ParamField path="options.limit" type="number">
  Page size. Defaults to `20`. Allowed range is `1` to `1000`.
</ParamField>

<ParamField path="options.swr" type="SWRInfiniteConfiguration<ListUsageEventsResponse, Error>">
  Optional [SWR Infinite config](https://swr.vercel.app/docs/pagination#useswrinfinite) for pagination/revalidation behavior.
</ParamField>

## Returns

<ParamField path="usageEvents" type="UsageEvent[]">
  Flattened list of fetched usage events.
</ParamField>

<ParamField path="isLoading" type="boolean">
  Whether the first page is loading.
</ParamField>

<ParamField path="isLoadingMore" type="boolean">
  Whether `getMore()` is currently loading the next page.
</ParamField>

<ParamField path="hasMore" type="boolean">
  Whether more events are available.
</ParamField>

<ParamField path="total" type="number">
  Total event count for the current query.
</ParamField>

<ParamField path="error" type="Error | null">
  Error from the latest request.
</ParamField>

<ParamField path="getMore" type="() => Promise<void>">
  Loads the next page when available.
</ParamField>

<ParamField path="refetch" type="() => Promise<void>">
  Revalidates loaded pages.
</ParamField>

## Example

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

export function UsageHistory() {
  const { usageEvents, isLoading, hasMore, isLoadingMore, getMore, error } =
    useUsageEvents<MyFeatures>("api_calls", { limit: 20 });

  if (isLoading) return <div>Loading usage events...</div>;
  if (error) return <div>Failed to load usage events.</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()} disabled={isLoadingMore}>
          {isLoadingMore ? "Loading..." : "Load more"}
        </button>
      ) : null}
    </div>
  );
}
```