Campaigns & groups

A campaign is a reusable definition of what to scan and how. A group bundles campaigns for bulk operations.

Creating a campaign

Open Campaigns -> New Campaign and configure:

• Type — a single URL, an ad tag (HTML snippet, or the URL of a page with the rendered creative), a VAST video tag (a VAST endpoint URL or raw VAST XML — fetched and played in a real browser so cloakers can't tell us apart from a real player), or ad discovery (a publisher page, scanned for the ads on it — see Ad discovery across devices for why the count depends on the device). One campaign carries one of them; a run fans it out across geos, devices, and repeats.
• Max ads to check — ad discovery only, 1 to 25, default 12. How many ad blocks we look for on each page before stopping. Every ad found is scanned and billed as a separate check, so this multiplies what a run costs; raise it for a large publisher whose inventory 12 truncates.
• Ad formats — ad discovery only, default all. Which formats to check: banners, video, and pops (pop-unders and tab-unders). Untick banners and video to check only a page's pops — the scan then neither screenshots nor clicks the banners, and none of them is billed.
• Geos — one or more locations to render from.
• Devices / emulators — the device profiles to use.
• Proxy — residential or datacenter, where applicable.
• Policy set — the rules results are judged against. If your organization has a default policy set, new campaigns use it unless you pick another set or explicitly choose none (no alerts).
• Labels — free-form metadata for filtering later.
• Repeats & retries — how many times to scan each combination, and how many extra attempts a technically failed scan gets.
• Schedule — manual, weekly, or a fixed interval.

Repeats and retries

Repeats multiply every geo × device combination a run fans out to. Three countries on four devices is 12 scans per run — and 60 at a repeat count of 5. Every repeat is a full scan with its own report; the Scans API carries the current ceiling on both the repeat count and the retry attempts.

How the repeats relate to each other is the browser session setting:

• Fresh each repeat (isolated, the default) — every repeat gets a clean browser and a new IP, so the repeats are independent samples. This is what catches a creative that only rotates in its malicious variant part of the time.
• Keep cookies (shared) — all repeats of one combination run in a single browser behind one IP, carrying cookies and local storage from one repeat to the next. Use it when the bad behaviour only appears on the second or third visit: frequency-capped creatives, cloakers that fingerprint a returning visitor, funnels that need a warmed-up session. Because the whole group runs as one crawl, repeats it never reaches — the browser failed to launch, the chain used up its wall-clock budget, or it hit too many failures in a row — come back as scans failed with crawl aborted: …, and with retries left at 0 that is where they stay. Not available on ad-discovery campaigns, which drive a browser of their own; the API rejects the combination.

Retries are about technical failures, not findings. Set retries on failure above 0 and a scan killed by a dead or rate-limited proxy, a navigation timeout, or a browser crash is crawled again. A failure a retry cannot fix — a blocked URL, an invalid ad tag or VAST document, or targeting that no proxy node can match — is final on the first attempt, and a scan that uses up its attempts ends as failed exactly as it would have without them. Each retry re-uses the same scan, so its id, its report link, and its place in the run never change.

Checking from a publisher page

A campaign can also carry a referrer — the publisher page its checks run from, and the single most common reason a cloaker behaves differently for us than for real traffic. For ad tag and VAST campaigns it is the page the tag is embedded in; for URL campaigns it is where the visitor came from.

Every scan a run of the campaign creates copies the campaign's referrer, whether the run was started by hand, from a group, or by a schedule. A scan submitted straight to the API carries only the referrer in its own request body — see Creating scans.

Ignoring your own click domains

When your checks run through your own direct links, the redirect chain starts on your click and tracking domains. Our detection treats them like any other hop, so a reputation hit on a click domain tags the material and raises an alert that says nothing about the offer.

Ignore first N domains removes them from detection. Set it to the number of your own domains at the head of the chain — 0 to 5, default 0 — and detection and tagging skip the first N unique domains counted from the entry point. Domains fold to their registrable form, so www.example.com and example.com count as one, and any other request to one of those domains is excluded too. Nothing else changes: the report still shows the full redirect chain.

Set it on the campaign and every scan of every run inherits it, discovered ads included. The value is frozen onto each scan when it is created, so re-checking an old scan skips what it skipped originally even if you have edited the campaign since.

Count carefully. A domain you skip is never checked by anything, so an N larger than the number of domains you own hides real findings on the offer. If you are unsure, open a completed scan and count the unique domains at the top of its redirect chain.

Running and re-running

Press Run to execute now. Each execution creates a run — a batch of scans visible in the campaign's run history. Scheduled campaigns run automatically; you can also cancel pending scans or a whole run.

Alert notifications

A campaign's Notifications section decides where its alerts go — inherit the organization's default destinations, override them with a picked list, or silence the campaign — and can route by a scan label (see Alerts). It is part of the campaign form, so one Save stores the campaign and its routing together, on create as well as on edit.

Over the API, send the same settings as an optional notifications block in POST /api/v1/campaigns or PATCH /api/v1/campaigns/{id}:

{
  "name": "Shared DSP direct links",
  "notifications": {
    "mode": "inherit",
    "destination_ids": [],
    "routing_label_key": "dspName"
  }
}

Omit the block to leave routing unchanged (or inherit, on create). The block needs the alert_notifications.manage permission and is checked before anything is written, so an invalid block leaves the campaign untouched. In the rare case the campaign is saved but its routing is not, the request fails with campaigns.notifications_not_applied — open the campaign and save its notifications again rather than repeating a create, which would add a second campaign.

Groups

The Groups tab lets you Run All, Cancel All, Archive/Unarchive, and Pause/Resume schedules across every campaign in the group at once — useful when you manage many campaigns for the same partner. A group's Last Run is the newest run of any campaign it holds.

Restarting many campaigns at once

Tick the campaigns or groups you want and press Run selected. Each selected campaign gets a new run — the same thing the per-row Run button does, quota included — so the confirmation dialog shows the campaign count and an estimated scan count first. Archived campaigns cannot run, so they are never counted and the archived list offers no selection at all; unarchive first. Scans join the normal queue at normal priority, so a large restart is processed alongside everything else rather than ahead of it.

If one campaign is blocked (say it is out of quota) the rest still start, and the result toast reports how many runs began and how many failed.

Finding campaigns

Both tabs of the campaigns hub, and the group page, filter by name and by Created / Last Run date range on top of the archived toggle and the group selector. Over the API the same filters are query parameters on GET /api/v1/campaigns and GET /api/v1/campaign-groups: q, created_from, created_to, last_run_from, last_run_to, and timezone. Dates are whole calendar days, both ends inclusive, interpreted in timezone (an IANA name, UTC by default). A from later than its to is rejected with 422 rather than silently returning nothing. Anything that has never run has no Last Run, so a last_run_* bound excludes it — filter on Created to find those.

Billing interaction

Running scans consumes quota or balance. If a run would exceed your plan limits a billing-blocked dialog explains what to do (top up or upgrade). See Billing.

Repeats multiply that cost — a campaign at repeat count 10 bills ten times what the same campaign billed at 1, since each repeat is a separate metered scan. The create form shows the estimate per run before you save. Retries do not add cost: a scan is metered when it finishes, so an attempt that failed and was re-crawled is never billed twice.