Skip to main content

​
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

FieldTypeRequiredDescription
offerIdstringNoSpecific offer ID. If omitted, aggregates across all offers.
totalBudgetnumberYesTotal budget amount (must be >= 0)
costPerConversionnumberYesCost per conversion (must be > 0)
lookbackDaysintegerNoDays 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

FieldTypeDescription
maxConversionsintegerMaximum conversions the budget can support
historicalConversionRatenumberObserved conversion rate (conversions / impressions)
estimatedDailyConversionsnumberAverage daily conversions in the lookback period
estimatedDaysUntilExhaustioninteger or nullProjected days until budget runs out
exhaustionDatestring or nullProjected exhaustion date (YYYY-MM-DD)
confidenceLevelstringhigh, medium, low, or insufficient_data
recommendationstringHuman-readable summary and guidance

​
Confidence Levels

LevelCriteria
high14+ active days and 50+ conversions
medium7+ active days and 20+ conversions
lowSome data but below medium thresholds
insufficient_dataNo conversions or no impressions recorded

​
Roles

admin, editor, viewer See also: Offers | Budgets