Skip to main content
POST
/
events
/
usage
Get usage statistics
curl --request POST \
  --url https://us.api.flexprice.io/v1/events/usage \
  --header 'Content-Type: */*' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "aggregation_type": "COUNT",
  "event_name": "api_request",
  "billing_anchor": "2024-03-05T14:30:45.123456789Z",
  "bucket_size": "MINUTE",
  "customer_id": "customer456",
  "end_time": "2024-03-20T00:00:00Z",
  "external_customer_id": "customer456",
  "filters": {},
  "group_by_property": "<string>",
  "multiplier": "<string>",
  "property_name": "request_size",
  "start_time": "2024-03-13T00:00:00Z",
  "window_size": "MINUTE"
}
'
{
  "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

*/*

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

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,
MONTH
​
customer_id
string
Example:

"customer456"

​
end_time
string
Example:

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

​
external_customer_id
string
Example:

"customer456"

​
filters
object
​
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.

​
multiplier
string
​
property_name
string

will be empty/ignored in case of COUNT

Example:

"request_size"

​
start_time
string
Example:

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

​
window_size
enum<string>
Available options:
MINUTE,
15MIN,
30MIN,
HOUR,
3HOUR,
6HOUR,
12HOUR,
DAY,
WEEK,
MONTH,
MONTH

Response

OK

​
event_name
string
​
results
object[]
​
type
enum<string>
Available options:
COUNT,
SUM,
AVG,
COUNT_UNIQUE,
LATEST,
SUM_WITH_MULTIPLIER,
MAX,
WEIGHTED_SUM
​
value
number