Guide — Budget Autopilot

Guide converts a demand source’s (DSP’s) daily spend target into a precise, real-time QPS (queries per second) limit. It prevents overspend, paces delivery evenly across the day, and coordinates across all three exchange regions through shared Redis state.

The problem Guide solves

Without pacing, a demand source with a $500 daily budget could exhaust it in the first 2 hours of the day — bidding aggressively on morning traffic and leaving nothing for the rest of the day. Alternatively, a conservative demand source might under-spend, wasting inventory.

Guide converts budget into the right QPS at every moment of the day.

How Guide works

1. DSP sets daily_budget = $500
         ↓
2. Guide calculates target spend rate
   rate = budget / remaining_hours_in_day
         ↓
3. Convert spend rate to QPS
   QPS = (rate / avg_clearing_price) × safety_factor
         ↓
4. Sync QPS limit across all regions via Redis
         ↓
5. Pathfinder enforces: DSP gets ≤ QPS bid requests/second
         ↓
6. Every 100ms: actual spend checked, QPS recalculated

Spend rate formula

target_rate_per_second = remaining_budget / remaining_seconds
qps_limit = (target_rate_per_second / avg_clearing_price_cents) × 100 × safety_factor

safety_factor defaults to 0.95 — builds in a 5% buffer to prevent overspend due to in-flight auctions.

Pacing strategies

Set pacing strategy via Demand → your demand source → Budget Settings → Pacing.

Cross-region coordination

Guide uses a shared Redis key to coordinate QPS limits across FRA, NYC, and LON:

guide:dsp:{dsp_id}:qps_limit      → current global QPS limit
guide:dsp:{dsp_id}:spend_today    → running spend total (cents)
guide:dsp:{dsp_id}:budget_daily   → configured daily budget (cents)

All three exchange pods read the same QPS limit. Spend is aggregated in real-time — a win in FRA immediately reduces remaining budget available in NYC and LON.

Budget exhaustion

When spend reaches the daily budget:

1. QPS limit drops to 0
2. Pathfinder stops sending bid requests to this DSP
3. Dashboard shows “Budget exhausted” status
4. DSP receives no more bid requests until midnight UTC (budget reset)

The daily budget resets at 00:00 UTC every day.

Per-campaign budgets (Delegate)

For Delegate demand sources, budgets can be set per campaign in the strategy JSON (daily_budget field). Guide tracks each campaign’s spend separately and pauses individual campaigns when their budget is exhausted, while other campaigns continue bidding.

Monitoring Guide

Dashboard → Demand → your demand source → Budget tab:

API:

GET /api/demand/sources/{DSP_ID}/health

Returns qps_current, qps_limit, and daily_budget_remaining_cents.

Adjusting budget mid-day

Budget and pacing strategy can be changed at any time. Guide recalculates QPS immediately using the new budget and remaining time in the day.

PUT /api/demand/sources/{DSP_ID}
{
  "daily_budget_cents": 75000
}