# 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.

{% hint style="info" %}
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.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.nexx360.io/campaign-delivery/pacing-and-capping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.