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

---

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