Skip to main content
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.
Setup first: see the React integration guide.
const result = useUsageEvents<MyFeatures>("api_calls", options?)

​
Parameters

​
featureKey
string
required
Feature key to list events for (typed to your tracked limit feature keys when using generated types).
​
options.enabled
boolean
Enable or disable fetching. Defaults to true.
​
options.period
"current" | "previous"
Usage period to query. Defaults to "current". Ignored when customRange is provided.
​
options.customRange
{ start: number; end: number }
Optional custom Unix-ms range. start and end are required when provided.
​
options.limit
number
Page size. Defaults to 20. Allowed range is 1 to 1000.
​
options.swr
SWRInfiniteConfiguration<ListUsageEventsResponse, Error>
Optional SWR Infinite config for pagination/revalidation behavior.

​
Returns

​
usageEvents
UsageEvent[]
Flattened list of fetched usage events.
​
isLoading
boolean
Whether the first page is loading.
​
isLoadingMore
boolean
Whether getMore() is currently loading the next page.
​
hasMore
boolean
Whether more events are available.
​
total
number
Total event count for the current query.
​
error
Error | null
Error from the latest request.
​
getMore
() => Promise<void>
Loads the next page when available.
​
refetch
() => Promise<void>
Revalidates loaded pages.

​
Example

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>
  );
}