Impression Pixel

GET /api/ad/pixel — Record an ad impression.

How It Works

The serve endpoint returns an impression_url in the ad response. When the ad is actually displayed to a user, you load this URL to record the impression. The pixel returns a 1x1 transparent GIF.

Impressions are what advertisers pay for, so it is important to only fire the pixel when the ad is genuinely visible to the user.

Referer requirement

Every pixel call is matched against the placement's registered domain via the request's Referer header. Browsers set this automatically, so a pixel fired from your registered domain just works. Pixels fired from a backend (Node, Python, PHP, etc.) must set the header explicitly to the URL of the page where the ad was rendered, otherwise the impression is rejected. Test origins like localhost, *.test, and file:// URLs are always rejected.

Full rules, the test-origin blocklist, and server-side code samples: Domain validation.

How to Fire It

Use an image tag or a fetch call:

<!-- Image tag (simplest) -->
<img src="{impression_url}" width="1" height="1" alt="" />

// Fetch (if you prefer JS)
fetch(impression_url);

Deduplication

The pixel deduplicates impressions by IP address, placement, and campaign. If the same combination is seen within a 1-hour window, the duplicate is silently ignored — the pixel still returns the GIF, but no impression is recorded and no budget is spent.

Server-Side Served Ads

When you serve ads from your backend using the ip parameter, the serve endpoint bakes that IP into the impression_url. This ensures deduplication works correctly even when the pixel is later loaded from the client.

Caching