Get usage statistics

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

POST /events/usage

Get usage statistics

cURL

curl --request POST \
  --url https://us.api.flexprice.io/v1/events/usage \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "event_name": "api_request",
  "billing_anchor": "2024-03-05T14:30:45.123456789Z",
  "customer_id": "customer456",
  "end_time": "2024-03-20T00:00:00Z",
  "external_customer_id": "customer456",
  "filters": {},
  "group_by": [
    "<string>"
  ],
  "group_by_property": "<string>",
  "multiplier": "<string>",
  "property_name": "request_size",
  "start_time": "2024-03-13T00:00:00Z",
  "timezone": "<string>"
}
'

200

{
  "event_name": "<string>",
  "results": [
    {
      "value": 123,
      "window_size": "<string>"
    }
  ],
  "type": "COUNT",
  "value": 123
}

Authorizations

x-api-key · string · header · required

Enter your API key in the format x-api-key <api-key>*

Body

application/json

Request body

aggregation_type · enum<string> · required

Available options: COUNT, SUM, AVG, COUNT_UNIQUE, LATEST, SUM_WITH_MULTIPLIER, MAX, WEIGHTED_SUM

event_name · string · required

Example:

"api_request"

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)

Example:

"2024-03-05T14:30:45.123456789Z"

bucket_size · enum<string>

Available options: MINUTE, 15MIN, 30MIN, HOUR, 3HOUR, 6HOUR, 12HOUR, DAY, WEEK, MONTH

customer_id · string

Example:

"customer456"

end_time · string<date-time>

Example:

"2024-03-20T00:00:00Z"

external_customer_id · string

Example:

"customer456"

filters · object

Show child attributes

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."} 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

Example:

"request_size"

start_time · string<date-time>

Example:

"2024-03-13T00:00:00Z"

timezone · string

window_size · enum<string>

Available options: MINUTE, 15MIN, 30MIN, HOUR, 3HOUR, 6HOUR, 12HOUR, DAY, WEEK, MONTH

Response

200

application/json

OK

event_name · string

results · object[]

Show child attributes

type · enum<string>

Available options: COUNT, SUM, AVG, COUNT_UNIQUE, LATEST, SUM_WITH_MULTIPLIER, MAX, WEIGHTED_SUM

value · number