> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

```json theme={null}
{
  "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](/api-reference/offers) | [Budgets](/api-reference/budgets)