API key scope:analytics:renewals:read for restricted keys. With apply_balance=true, also require payment-history:read. Unrestricted keys support both variants. Insufficient scope or financial access returns 403 FORBIDDEN.
Path Parameters
project_idstringrequired
Project UUID.
Query Parameters
range_typestring
days (default), weeks or months.
range_valueinteger
Positive length; maximum 365 days, 52 weeks or 12 months. Defaults: 30 days, 4 weeks or 1 month.
currencystring
Supported currency code: 3–9 uppercase letters or digits.
apply_balanceboolean|integer
true, false, 1 or 0; default false.
The range begins today in UTC and ends exclusively after the selected duration. All results contain daily rows, including zero-filled days. There is no pagination or request body. Invalid query values return 422 VALIDATION_ERROR.
data.calendar and data.meta are required. Every calendar row requires date (UTC ISO datetime at midnight), renewal_count (nonnegative integer), and expected_revenue (nonnegative decimal string). Optional expected_balance_offset and net_expected_revenue are nonnegative decimal strings, never null.
Revenue totals follow currency precision. Do not assume two decimal places or convert amounts to binary floating-point numbers. Use the decimal amount contract.
All metadata fields below are required unless marked optional.
Fields
Type
range_type
days, weeks or months
range_value
Integer
start_date, end_date
UTC ISO datetime strings at midnight; end is exclusive
Objects mapping currency codes to nonnegative decimal strings; may be empty
conversion_errors
Array of objects requiring string from_currency, to_currency and reason
threshold
Null or object with required decimal-string amount and string currency; currently null for this endpoint
projection
Object requiring basis (run_rate or accrued), numeric max_factor and integer clamped_count; currently {basis:"accrued", max_factor:1, clamped_count:0}
forecast_limitations
String array
applied_balance, balance_unavailable
Optional booleans
total_balance_offset, total_net_expected_revenue
Optional nonnegative decimal strings
fx_excluded_from_offset
Optional integer
Optional balance fields accompany apply_balance=true and are not nullable. A failed lookup can return a successful gross-only result with applied_balance:false and balance_unavailable:true. That response does not prove balances were applied.
