Retrieve combined analytics with ROI, margin, and detailed breakdowns. If start_time and end_time are not provided, defaults to last 7 days.
curl --request POST \
--url https://api.cloud.flexprice.io/v1/costs/analytics \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"end_time": "<string>",
"expand": [
"<string>"
],
"external_customer_id": "<string>",
"feature_ids": [
"<string>"
],
"limit": 123,
"offset": 123,
"start_time": "<string>"
}
'{
"cost_analytics": [
{
"cost_by_period": [
{
"cost": "<string>",
"event_count": 123,
"quantity": "<string>",
"timestamp": "<string>"
}
],
"costsheet_id": "<string>",
"currency": "<string>",
"customer_id": "<string>",
"external_customer_id": "<string>",
"meter": {
"aggregation": {
"bucket_size": "MINUTE",
"field": "<string>",
"multiplier": "<string>",
"type": "COUNT"
},
"created_at": "<string>",
"created_by": "<string>",
"environment_id": "<string>",
"event_name": "<string>",
"filters": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"id": "<string>",
"name": "<string>",
"reset_usage": "BILLING_PERIOD",
"status": "published",
"tenant_id": "<string>",
"updated_at": "<string>",
"updated_by": "<string>"
},
"meter_id": "<string>",
"meter_name": "<string>",
"price": {
"amount": "<string>",
"billing_cadence": "RECURRING",
"billing_model": "FLAT_FEE",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"conversion_rate": "<string>",
"created_at": "<string>",
"created_by": "<string>",
"currency": "<string>",
"description": "<string>",
"display_amount": "<string>",
"display_price_unit_amount": "<string>",
"end_date": "<string>",
"entity_id": "<string>",
"entity_type": "PLAN",
"environment_id": "<string>",
"group_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"lookup_key": "<string>",
"metadata": {},
"meter_id": "<string>",
"parent_price_id": "<string>",
"price_unit": "<string>",
"price_unit_amount": "<string>",
"price_unit_id": "<string>",
"price_unit_tiers": [
{
"flat_amount": "<string>",
"unit_amount": "<string>",
"up_to": 123
}
],
"price_unit_type": "FIAT",
"start_date": "<string>",
"status": "published",
"tenant_id": "<string>",
"tier_mode": "VOLUME",
"tiers": [
{
"flat_amount": "<string>",
"unit_amount": "<string>",
"up_to": 123
}
],
"transform_quantity": {
"divide_by": 123,
"round": "<string>"
},
"trial_period": 123,
"type": "USAGE",
"updated_at": "<string>",
"updated_by": "<string>"
},
"price_id": "<string>",
"properties": {},
"source": "<string>",
"total_cost": "<string>",
"total_events": 123,
"total_quantity": "<string>"
}
],
"currency": "<string>",
"end_time": "<string>",
"margin": "<string>",
"margin_percent": "<string>",
"roi": "<string>",
"roi_percent": "<string>",
"start_time": "<string>",
"total_cost": "<string>",
"total_revenue": "<string>"
}Enter your API key in the format x-api-key <api-key>*
Combined analytics request (start_time/end_time optional - defaults to last 7 days)
Expand options - specify which entities to expand
Optional - for specific customer
Additional filters
Pagination
Time range fields (optional - defaults to last 7 days if not provided)
OK
Cost analytics array (flattened from nested structure)
Show child attributes
Metadata
Show child attributes
Show child attributes
MINUTE, 15MIN, 30MIN, HOUR, 3HOUR, 6HOUR, 12HOUR, DAY, WEEK, MONTH Field is the key in $event.properties on which the aggregation is to be applied For ex if the aggregation type is sum for API usage, the field could be "duration_ms"
Multiplier is the multiplier for the aggregation For ex if the aggregation type is sum_with_multiplier for API usage, the multiplier could be 1000 to scale up by a factor of 1000. If not provided, it will be null.
COUNT, SUM, AVG, COUNT_UNIQUE, LATEST, SUM_WITH_MULTIPLIER, MAX, WEIGHTED_SUM EnvironmentID is the environment identifier for the meter
EventName is the unique identifier for the event that this meter is tracking It is a mandatory field in the events table and hence being used as the primary matching field We can have multiple meters tracking the same event but with different filters and aggregation
Filters define the criteria for the meter to be applied on the events before aggregation It also defines the possible values on which later the charges will be applied
Show child attributes
Key is the key for the filter from $event.properties Currently we support only first level keys in the properties and not nested keys
Values are the possible values for the filter to be considered for the meter For ex "model_name" could have values "o1-mini", "gpt-4o" etc
ID is the unique identifier for the meter
Name is the display name of the meter
BILLING_PERIOD, NEVER published, deleted, archived Show child attributes
Amount stored in main currency units (e.g., dollars, not cents) For USD: 12.50 means $12.50
RECURRING, ONETIME FLAT_FEE, PACKAGE, TIERED MONTHLY, ANNUAL, WEEKLY, DAILY, QUARTERLY, HALF_YEARLY BillingPeriodCount is the count of the billing period ex 1, 3, 6, 12
ConversionRate is the rate of the price unit to the base currency For BTC: 1 BTC = 100000000 USD
Currency 3 digit ISO currency code in lowercase ex usd, eur, gbp
Description of the price
DisplayAmount is the formatted amount with currency symbol For USD: $12.50
DisplayPriceUnitAmount is the formatted amount with price unit symbol For BTC: 0.00000001 BTC
EndDate is the end date of the price
EntityID holds the value of the "entity_id" field.
PLAN, SUBSCRIPTION, ADDON, PRICE, COSTSHEET EnvironmentID is the environment identifier for the price
GroupID references the group this price belongs to
ID uuid identifier for the price
ARREAR, ADVANCE LookupKey used for looking up the price in the database
MeterID is the id of the meter for usage based pricing
ParentPriceID references the root price (always set for price lineage tracking)
PriceUnit 3 digit ISO currency code in lowercase ex btc For BTC: btc
PriceUnitAmount is the amount stored in price unit For BTC: 0.00000001 means 0.00000001 BTC
PriceUnitID is the id of the price unit
PriceUnitTiers are the tiers for the price unit
Show child attributes
flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c"
unit_amount is the amount per unit for the given tier
up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE.
FIAT, CUSTOM StartDate is the start date of the price
published, deleted, archived VOLUME, SLAB Show child attributes
flat_amount is the flat amount for the given tier (optional) Applied on top of unit_amount*quantity. Useful for cases like "2.7$ + 5c"
unit_amount is the amount per unit for the given tier
up_to is the quantity up to which this tier applies. It is null for the last tier. IMPORTANT: Tier boundaries are INCLUSIVE.
TrialPeriod is the number of days for the trial period Note: This is only applicable for recurring prices (BILLING_CADENCE_RECURRING)
USAGE, FIXED Aggregated metrics
Revenue - Cost
(Margin / Revenue) * 100
(Revenue - Cost) / Cost
ROI * 100
Derived metrics
curl --request POST \
--url https://api.cloud.flexprice.io/v1/costs/analytics \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"end_time": "<string>",
"expand": [
"<string>"
],
"external_customer_id": "<string>",
"feature_ids": [
"<string>"
],
"limit": 123,
"offset": 123,
"start_time": "<string>"
}
'{
"cost_analytics": [
{
"cost_by_period": [
{
"cost": "<string>",
"event_count": 123,
"quantity": "<string>",
"timestamp": "<string>"
}
],
"costsheet_id": "<string>",
"currency": "<string>",
"customer_id": "<string>",
"external_customer_id": "<string>",
"meter": {
"aggregation": {
"bucket_size": "MINUTE",
"field": "<string>",
"multiplier": "<string>",
"type": "COUNT"
},
"created_at": "<string>",
"created_by": "<string>",
"environment_id": "<string>",
"event_name": "<string>",
"filters": [
{
"key": "<string>",
"values": [
"<string>"
]
}
],
"id": "<string>",
"name": "<string>",
"reset_usage": "BILLING_PERIOD",
"status": "published",
"tenant_id": "<string>",
"updated_at": "<string>",
"updated_by": "<string>"
},
"meter_id": "<string>",
"meter_name": "<string>",
"price": {
"amount": "<string>",
"billing_cadence": "RECURRING",
"billing_model": "FLAT_FEE",
"billing_period": "MONTHLY",
"billing_period_count": 123,
"conversion_rate": "<string>",
"created_at": "<string>",
"created_by": "<string>",
"currency": "<string>",
"description": "<string>",
"display_amount": "<string>",
"display_price_unit_amount": "<string>",
"end_date": "<string>",
"entity_id": "<string>",
"entity_type": "PLAN",
"environment_id": "<string>",
"group_id": "<string>",
"id": "<string>",
"invoice_cadence": "ARREAR",
"lookup_key": "<string>",
"metadata": {},
"meter_id": "<string>",
"parent_price_id": "<string>",
"price_unit": "<string>",
"price_unit_amount": "<string>",
"price_unit_id": "<string>",
"price_unit_tiers": [
{
"flat_amount": "<string>",
"unit_amount": "<string>",
"up_to": 123
}
],
"price_unit_type": "FIAT",
"start_date": "<string>",
"status": "published",
"tenant_id": "<string>",
"tier_mode": "VOLUME",
"tiers": [
{
"flat_amount": "<string>",
"unit_amount": "<string>",
"up_to": 123
}
],
"transform_quantity": {
"divide_by": 123,
"round": "<string>"
},
"trial_period": 123,
"type": "USAGE",
"updated_at": "<string>",
"updated_by": "<string>"
},
"price_id": "<string>",
"properties": {},
"source": "<string>",
"total_cost": "<string>",
"total_events": 123,
"total_quantity": "<string>"
}
],
"currency": "<string>",
"end_time": "<string>",
"margin": "<string>",
"margin_percent": "<string>",
"roi": "<string>",
"roi_percent": "<string>",
"start_time": "<string>",
"total_cost": "<string>",
"total_revenue": "<string>"
}