Budget Forecast

Project budget exhaustion dates based on historical conversion rates and spend patterns.

POST /api/v1/offers/budget-forecast

Projects when an offer’s budget will be exhausted based on historical conversion rates. Uses interaction summary data (with raw interaction history fallback) to estimate daily conversion volume.

Request Body

Field	Type	Required	Description
offerId	string	No	Specific offer ID. If omitted, aggregates across all offers.
totalBudget	number	Yes	Total budget amount (must be >= 0)
costPerConversion	number	Yes	Cost per conversion (must be > 0)
lookbackDays	integer	No	Days of history to analyze (1-365, default: 30)

Example

curl -X POST https://playground.kaireonai.com/api/v1/offers/budget-forecast \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "offerId": "off_001",
    "totalBudget": 50000,
    "costPerConversion": 25,
    "lookbackDays": 30
  }'

Response

{
  "totalBudget": 50000,
  "costPerConversion": 25,
  "maxConversions": 2000,
  "historicalConversionRate": 0.0234,
  "estimatedDailyConversions": 15.3,
  "estimatedDaysUntilExhaustion": 131,
  "exhaustionDate": "2026-08-08",
  "confidenceLevel": "high",
  "recommendation": "Budget will last approximately 4.4 months at current conversion rates."
}

Response Fields

Field	Type	Description
maxConversions	integer	Maximum conversions the budget can support
historicalConversionRate	number	Observed conversion rate (conversions / impressions)
estimatedDailyConversions	number	Average daily conversions in the lookback period
estimatedDaysUntilExhaustion	integer or null	Projected days until budget runs out
exhaustionDate	string or null	Projected exhaustion date (YYYY-MM-DD)
confidenceLevel	string	high, medium, low, or insufficient_data
recommendation	string	Human-readable summary and guidance

Confidence Levels

Level	Criteria
high	14+ active days and 50+ conversions
medium	7+ active days and 20+ conversions
low	Some data but below medium thresholds
insufficient_data	No conversions or no impressions recorded

Roles

admin, editor, viewer

See also: Offers | Budgets