Pacing and Capping

Pacing and capping control how fast and how much a line item delivers against its goal.

Goal types

Each line item has a delivery goal defined by:

Field	Description
goalType	impressions, clicks, or spend
quantity	The target number of impressions, clicks, or spend amount
pacingType	How the delivery is distributed over time

Pacing types

Type	Description
asap	Deliver as fast as possible. The delivery ratio starts high and decreases as the goal is approached.
even	Distribute delivery evenly over the campaign duration. The ratio is adjusted to maintain a uniform pace.
frontloaded	Deliver more aggressively early in the campaign, tapering off toward the end.

The delivery ratio (0 to 1) is a dynamic value calculated externally based on:

• Current progress toward the goal

• Time remaining until endDate

• The selected pacing type

A creative is eligible to bid when its delivery.ratio > random(). This provides probabilistic traffic control without hard per-request caps.

Delivery capping

Delivery capping provides hourly hard caps to prevent overdelivery. It applies at two levels:

Line item capping

When a line item (without splits) exceeds its hourly delivery cap, all its creatives have their delivery ratio set to 0, effectively blocking delivery until the next hour.

Split capping

Each split can be independently capped. When a split exceeds its hourly cap, only that split's creatives are blocked. Other splits and the line item's base creatives remain unaffected.

How capping works

• Caps are checked every 60 seconds

• Cap thresholds and current counts are stored in Valkey (Redis)

• Fail-closed: If the cap value cannot be read from Valkey, delivery is blocked to prevent overdelivery

• Capped entities are tracked in memory and applied to all subsequent bid evaluations until the next check

CPC (cost-per-click) campaigns

Line items with goalType: clicks use a special CPC delivery mechanism:

CPC segments

CPC line items can define cpcSegments -- targeting segments with domain and GPID-based matching:

Field	Description
id	Segment identifier
cpm	CPC bid price for this segment
targeting	Array of { domain, gpid[] } rules, or null for catch-all

Segment matching

When a CPC line item is evaluated, the system matches the bid request against CPC segments using a scoring system:

Score	Match type
0	No targeting match (catch-all fallback)
1	Domain-only match
2	Domain + GPID match (most specific)

The segment with the highest score wins. If scores are tied, the higher CPM wins. The matched segment's CPM overrides the line item's base rate.

Spend guard

CPC campaigns include a spend guard that checks whether the campaign's spend budget is exhausted. If the budget is reached, the line item stops bidding.

CPC creatives with a matched segment bypass the delivery ratio filter, ensuring they always bid when eligible. This is because CPC delivery is controlled by the spend guard rather than ratio-based pacing.