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: 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>"
}
'
import requests

url = "https://us.api.flexprice.io/v1/events/usage"

payload = {
"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>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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>'
})
};

fetch('https://us.api.flexprice.io/v1/events/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://us.api.flexprice.io/v1/events/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://us.api.flexprice.io/v1/events/usage"

payload := strings.NewReader("{\n \"event_name\": \"api_request\",\n \"billing_anchor\": \"2024-03-05T14:30:45.123456789Z\",\n \"customer_id\": \"customer456\",\n \"end_time\": \"2024-03-20T00:00:00Z\",\n \"external_customer_id\": \"customer456\",\n \"filters\": {},\n \"group_by\": [\n \"<string>\"\n ],\n \"group_by_property\": \"<string>\",\n \"multiplier\": \"<string>\",\n \"property_name\": \"request_size\",\n \"start_time\": \"2024-03-13T00:00:00Z\",\n \"timezone\": \"<string>\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://us.api.flexprice.io/v1/events/usage")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"event_name\": \"api_request\",\n \"billing_anchor\": \"2024-03-05T14:30:45.123456789Z\",\n \"customer_id\": \"customer456\",\n \"end_time\": \"2024-03-20T00:00:00Z\",\n \"external_customer_id\": \"customer456\",\n \"filters\": {},\n \"group_by\": [\n \"<string>\"\n ],\n \"group_by_property\": \"<string>\",\n \"multiplier\": \"<string>\",\n \"property_name\": \"request_size\",\n \"start_time\": \"2024-03-13T00:00:00Z\",\n \"timezone\": \"<string>\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://us.api.flexprice.io/v1/events/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"event_name\": \"api_request\",\n \"billing_anchor\": \"2024-03-05T14:30:45.123456789Z\",\n \"customer_id\": \"customer456\",\n \"end_time\": \"2024-03-20T00:00:00Z\",\n \"external_customer_id\": \"customer456\",\n \"filters\": {},\n \"group_by\": [\n \"<string>\"\n ],\n \"group_by_property\": \"<string>\",\n \"multiplier\": \"<string>\",\n \"property_name\": \"request_size\",\n \"start_time\": \"2024-03-13T00:00:00Z\",\n \"timezone\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "event_name": "<string>",
  "results": [
    {
      "value": 123,
      "window_size": "<string>"
    }
  ],
  "value": 123
}
{
"http_status_code": 123,
"message": "<string>"
}
{
"http_status_code": 123,
"message": "<string>"
}

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

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