Skip to main content

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.

See also: Frequency Caps REST API reference for request/response shapes, status codes, and error semantics.

​
Frequency Caps

Frequency caps are system-wide delivery caps that automatically block offers when their budget is exhausted. They operate independently of contact policies — contact policies protect individual customers, while frequency caps protect the business from over-delivery.

​
Cap Scopes

ScopeWhat It ControlsExample
offerCaps delivery of a specific offer”Win-Back: max 20 impressions/day”
categoryCaps all offers in a category”Auto Insurance: max 500/day”
channelCaps all delivery on a channel”Direct Mail: max 50/day”

​
How It Works

  1. Frequency caps are checked during the Contact Policy stage of the decision pipeline
  2. The system queries frequency_caps for the tenant where enabled=true and resetAt > now()
  3. Any cap where currentCount >= maxVolume adds its scope to the exclusion set
  4. Candidates matching excluded scopes (offer, category, or channel) are filtered out

​
Counter Increment

The currentCount is incremented by the Respond API when an impression outcome is recorded:
  • Only impression-type outcomes increment the counter (clicks/conversions don’t)
  • The increment is atomic (prevents race conditions in concurrent delivery)
  • Counters reset when resetAt passes (configured per cap)

​
Configuration

Frequency caps are stored in the frequency_caps table:
FieldTypeDescription
namestringHuman-readable name
scopeenumoffer, category, or channel
scopeIdstringID of the offer, category, or channel
maxVolumeintegerMaximum delivery count per period
periodstringReset period: daily, weekly, monthly
currentCountintegerCurrent delivery count (auto-incremented)
resetAttimestampWhen the counter resets
enabledbooleanWhether the cap is active

​
Best Practices

  • Set channel-level caps for batch channels (Direct Mail, SMS) to control vendor costs
  • Set offer-level caps for limited-inventory promotions
  • Monitor currentCount vs maxVolume in the Operations dashboard
  • Use allowPartial in the Group node to gracefully handle exhausted placements