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

# useAggregateEvents

> Show event usage to your customers in a timeseries chart

The `useAggregateEvents` hook provides access to usage analytics and reporting data.

It fetches data from the [/events/aggregate](/api-reference/events/aggregate-events) endpoint, that can be displayed in a chart (typically via a library like Recharts).

<Tip>
  Learn how to setup Autumn hooks in the [Getting Started](/documentation/getting-started/setup) guide.
</Tip>

## Parameters

<ParamField body="featureId" type="string | string[]" required>
  The feature ID or array of feature IDs to query usage data for.
</ParamField>

<ParamField body="groupBy" type="string">
  Aggregate data by an event properties paramater. This property is metadata passed in the event endpoint. Should be formatted as `properties.<event_property>`
</ParamField>

<ParamField body="range" type="string">
  Time range for the analytics query. Available options: "24h", "7d", "30d", "90d", "last\_cycle", "1bc", "3bc". "bc" refers to billing cycle. Defaults to "30d" if not provided.
</ParamField>

<ParamField body="binSize" type="string">
  Granularity of the time bins for the data points. Available options: "day", "hour". Defaults to "day".
</ParamField>

<ParamField body="customRange" type="object">
  Custom date range for the query. When provided, overrides the `range` parameter.

  <Expandable title="customRange properties">
    <ParamField body="start" type="number" required>
      Start timestamp (Unix timestamp in milliseconds)
    </ParamField>

    <ParamField body="end" type="number" required>
      End timestamp (Unix timestamp in milliseconds)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="queryOptions" type="UseQueryOptions">
  Optional [TanStack Query options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) to customize caching and refetching behavior. Common options include `enabled`, `staleTime`, and `refetchInterval`.
</ParamField>

## Returns

### `list`

Array of aggregated event data points for each time period. Each `AggregatedEventRow` includes:

* `period`: Unix timestamp in milliseconds representing the start of the time period
* Dynamic properties for each queried `featureId` with their usage amounts

<Expandable title="list example">
  ```json theme={null}
  [
      {
          "period": 1765411200000,
          "basic_messages": 3,
          "premium_messages": 5
      },
      {
          "period": 1765497600000,
          "basic_messages": 1,
          "premium_messages": 2
      },
  ]
  ```
</Expandable>

### `total`

Aggregate totals for the entire time range. Returns a record with each feature ID as the key and an object containing:

* `count`: Total number of events
* `sum`: Total sum of all event values

### `isLoading`

Boolean indicating whether the event data is currently being fetched.

### `error`

Any `AutumnError` that occurred while fetching event data.

### `refetch()`

Function to manually refetch the event data.