Estimate
Estimate
GET /estimate requires the read scope. It calls one database function, estimate_budget_delivery. The public site, Ads Manager, and this API use that same function.
curl 'https://tyfrhxfejrawgdlhryfu.supabase.co/functions/v1/advertiser-api/estimate?deposit_cents=5000&billing_model=cpm&apply_first_deposit_bonus=true' \
-H 'Authorization: Bearer idl_adv_xxx'
Pass budget_cents or deposit_cents. Amounts are euro cents. billing_model is cpm or cpc. Omit bid_cents to use the median price charged in the window. countries and placements are comma-separated. daily=true treats budget_cents as one day.
apply_first_deposit_bonus=true adds the configured first-deposit bonus when the deposit qualifies. A first deposit of €50 is estimated as €100 of credit.
The response is { "data": { ... } }.
| Field | Meaning |
|---|---|
status | ok or not_enough_data |
reason | Why the range is empty or withheld. too_few_wins means the bid clears too little of the observed market. budget_below_one_unit means the credit does not cover one billed unit. |
window_start, window_end, window_days | The delivery window. The length is platform_settings.budget_estimate.windowDays (default 28). |
credit_cents | What the estimate spends, after a bonus when one applies |
impressions, clicks | { "low", "high" }, or null |
clicks_status | not_enough_data when there are not enough clicks to publish a click range |
win_share | Share of priced auctions in the window below this bid's eCPM. Omitted when that share is too small to publish. |
market_ecpm_cents | 25th and 75th percentile of charged prices in the slice, in eCPM cents |
method | The calculation, in one paragraph |
How the range is calculated
Inventory is the impressions delivered in the window, for the countries and placements you set. A placement matches an ad-set placement, an ad format, or the surface stored on the impression (editor).
A bid wins the share of those auctions whose observed charged price, converted to eCPM, is below the bid. CPM eCPM is the bid in cents per 1 000 impressions. CPC eCPM is the bid times the smoothed CTR (clicks + 1) / (impressions + 50), the same prior delivery uses in serve_ad_v2_paid and serve_chat_ad_core.
Charged prices come from billed CPM impressions, CPC click charges, and auction clearing prices when a log row is tied to the impression. The price this bid would pay is the 25th to 75th percentile of the auctions it would win, capped at the bid. CPM impressions are billed in whole cents, at least 1 cent, the same way an impression is recorded.
The credit cannot buy more than the inventory that bid would have won over the horizon. A daily budget uses one day of that inventory. The low end is reduced by safetyMargin (default 0.2). When there are enough clicks, the click bounds also use an 80% Wilson interval of the observed CTR.
Empty chat requests are extra inventory only when that unfilled count itself clears the minimum volume.
Not enough data
If the slice has fewer impressions or priced auctions than minImpressions and minPriceObservations, status is not_enough_data. Counts are omitted. The same happens for clicks below minClicks: the impression range can still be present, and clicks is null.
The result is a platform aggregate. It does not include another advertiser's campaigns, ads, or bids.
An invalid bid, country, or amount is HTTP 400 with invalid_request. not_enough_data is HTTP 200.
The MCP tool is estimate_budget. It sends this route.