---
title: "Get usage statistics"
method: POST
path: "/events/usage"
tags: ["Events"]
---

# Get usage statistics

`POST /events/usage`

Use when building usage reports or dashboards across events. Supports filters and grouping; defaults to last 7 days if no range provided.

## Request body

- GetUsageRequest
  - `aggregation_type` 'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM', required
  - `billing_anchor` string, date-time — BillingAnchor enables custom monthly billing periods for usage aggregation. When to use: - WindowSize = "MONTH" AND you need custom monthly periods (not calendar months) - Subscription billing that doesn't align with calendar months - Example: Customer signed up on 15th, so billing periods are 15th to 15th When NOT to use: - WindowSize != "MONTH" (ignored for DAY, HOUR, WEEK, etc.) - Standard calendar-based billing (1st to 1st of each month) Example values: - "2024-03-05T14:30:45.123456789Z" (5th of each month at 2:30:45 PM) - "2024-01-15T00:00:00Z" (15th of each month at midnight) - "2024-02-29T12:00:00Z" (29th of each month at noon - handles leap years)
  - `bucket_size` 'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH'
  - `customer_id` string
  - `end_time` string, date-time
  - `event_name` string, required
  - `external_customer_id` string
  - `filters` object
  - `group_by` string[] — GroupBy lists the analytics group_by dimensions. - "source" — group by event source column - "properties.X" — group by JSON property X
  - `group_by_property` string — GroupByProperty is the property name in event.properties to group by before aggregating. When set, aggregation is applied per unique value of this property within each bucket, then the per-group results are summed to produce the bucket total. Deprecated: prefer GroupBy []string{"properties.<X>"} for parity with other analytics endpoints. ToUsageParams translates this field into GroupBy when GroupBy is otherwise empty.
  - `multiplier` string
  - `property_name` string — will be empty/ignored in case of COUNT
  - `start_time` string, date-time
  - `timezone` string
  - `window_size` 'MINUTE' | '15MIN' | '30MIN' | 'HOUR' | '3HOUR' | '6HOUR' | '12HOUR' | 'DAY' | 'WEEK' | 'MONTH'

## Response `200`

OK

- GetUsageResponse
  - `event_name` string
  - `results` UsageResult[]
    - `value` number
    - `window_size` string
  - `type` 'COUNT' | 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'LATEST' | 'SUM_WITH_MULTIPLIER' | 'MAX' | 'WEIGHTED_SUM'
  - `value` number

## Other responses

- `400` — Invalid request
- `500` — Server error

## Changes

- **2026-06-29** `cef2964c102c` — 2 info
  - added the new optional request property `group_by`
  - added the new optional request property `timezone`
- **2026-05-18** `f62d8a5fe7cf` — 4 warning
  - removed the optional property `details` from the response with the `400` status
  - removed the optional property `details` from the response with the `500` status
  - added the new `too_many_requests` enum value to the `code` response property for the response status `400`
  - added the new `too_many_requests` enum value to the `code` response property for the response status `500`
- **2026-04-06** `4ded3711f401` — 4 warning, 8 info
  - removed the optional property `error` from the response with the `400` status
  - removed the optional property `error` from the response with the `500` status
  - removed the optional property `success` from the response with the `400` status
  - removed the optional property `success` from the response with the `500` status
  - …8 more
- **2026-04-04** `d1860fe0ee67` — 3 breaking
  - the `billing_anchor` request property type/format changed from `string`/`` to `string`/`date-time`
  - the `end_time` request property type/format changed from `string`/`` to `string`/`date-time`
  - the `start_time` request property type/format changed from `string`/`` to `string`/`date-time`

[Change history](https://skmtc.dev/flexprice/apis/flexprice-api-2/changes/events/usage/post.md)

---

[API](https://skmtc.dev/flexprice/apis/flexprice-api-2.md) · [All operations](https://skmtc.dev/flexprice/apis/flexprice-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flexprice/flexprice-api-2/revisions/da8f268dc77d/schema)