Auto-rule and script SDK
A reference for what is available inside the code of an auto-pause rule and a user script: the ad object's fields, the functions for pausing and resuming, and the selectors for picking ads. Captions for all fields with descriptions are also available right in the rule editor — in the ad.* keys reference side panel (search by name and description).
This is the Server SDK — commands that run on the Qubix server, as opposed to the Browser SDK that runs in the visitor's browser. The Server SDK is synchronous: sql, ctx.fetch, and state return a value directly — no await or Promises.
The ad object
In an auto-pause rule, you receive a single ad object — this is the ad the check is being run for. Through it you read all metrics and attributes. All available fields are grouped by scope.
| Group | Field prefix | What's inside |
|---|---|---|
| Ad | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Metrics and attributes of the ad itself |
| Creative | ad.creo_* | Metrics by creative (all ads with this creative) |
| Geo | ad.geo_* | Metrics by country |
| Offer | ad.offer_* | Metrics and parameters of the offer (payout, cap) |
| Network | ad.network_* | Metrics by network |
| Previous period | ad.prev_* | The same metrics for the previous period (for comparison) |
The full list of metrics, time windows (_1h…_total), and the meaning of each prefix — in the Metrics and columns section.
Accessing a non-existent field (ad.something_wrong) immediately aborts the rule with an error. Check names against the reference in the editor.
Pause
Three functions — by scope. The ad, the ad set, and the campaign.
| Function | Action |
|---|---|
pauseAd(duration, reason?) | Pause the current ad |
pauseAdset({ adsetId, duration, reason? }) | Pause the ad set |
pauseCampaign({ campaignId, duration, reason? }) | Pause the campaign |
For pauseAd it's enough to pass the duration as a string; for the ad set and campaign the object form with an explicit adsetId / campaignId is required.
Durations (duration):
| Value | Meaning |
|---|---|
6h / 12h / 24h | Pause for N hours |
next_day_target_geo | Until the start of the next day in the target country's time |
next_day_ad_account | Until the start of the next day in the ad account's time |
permanent | A permanent pause |
while_matches | While the rule condition holds |
reason is an optional comment that goes into the log. If omitted, the rule name is substituted.
Resume
| Function | Action |
|---|---|
activateAd(reason?) | Resume the current ad |
activateAdset({ adsetId, reason? }) | Resume the ad set |
activateCampaign({ campaignId, reason? }) | Resume the campaign |
Neighboring ads
Inside a rule, you can look at other ads in the same ad set or campaign — for example, to stop the whole ad set if only one ad dropped.
| Function | Returns |
|---|---|
getAd(id) | An ad by its ad_id |
getAdset() | All ads in the current ad's ad set |
getCampaign() | All ads in the current ad's campaign |
Also available are console.log / console.warn / console.error for debug output and skipNextRules() — skip the remaining rules for this ad.
QubixApp selectors (for scripts)
In user scripts, the QubixApp object is available — it selects ads, ad sets, and campaigns by conditions. Each selected element has its own statistics and pause methods.
| Method | Returns a selection of |
|---|---|
QubixApp.ads() | Ads |
QubixApp.adsets() | Ad sets |
QubixApp.campaigns() | Campaigns |
Selection methods (chained):
| Method | What it does |
|---|---|
.withCondition(sql) | Filter by a condition |
.filter(fn) | Filter with a function |
.orderBy(field, dir) | Sort ('asc' / 'desc') |
.withLimit(n) | Limit the number of elements |
.get() | Get an array of elements |
.first() | Get the first element |
Element methods:
| Method | Action |
|---|---|
.pause({ duration, reason? }) | Pause |
.activate({ reason? }) | Resume |
.getStatsFor(period) | Metrics for a window ('1h'…'total') |
.getAds() | Ads inside an ad set / campaign |
.getAdsets() | Ad sets inside a campaign |
getStatsFor returns a set of metrics for the selected window: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Script context
In scripts, the ctx object is additionally available.
| Field / method | Purpose |
|---|---|
ctx.state.get/set/delete/keys | Persisting state between runs |
ctx.fetch(url, opts?) | An HTTP request (the host must be in the allowlist, see JavaScript in settings) |
ctx.now() | The current time |
ctx.script | Information about the current script |
The ctx object (including ctx.fetch) exists only in scripts — it is not available inside auto-pause rules. And even in scripts, ctx.fetch works only in a real run on the server: in a browser test run network calls are disabled, so verify via a real run.
Shared state
Besides its private ctx.state, there is a shared store ctx.state.global, visible to every script, rule, and site handler at once.
| Method | Action |
|---|---|
ctx.state.global.get(key) | Read a value |
ctx.state.global.keys() | List the keys |
ctx.state.global.set(key, value) | Write a value |
ctx.state.global.delete(key) | Delete a value |
Any script or rule can read the shared store. Writing (set / delete) is allowed only from a script or rule owned by an administrator — otherwise the write throws an error. Handy for shared lookups: the administrator writes a value once, everyone else reads it.
ctx.fetch: a 10-second timeout by default (30 max), a response up to 1 MB, no more than 20 requests per run.sql: a single query returns at most a few thousand rows — the administrator sets the exact cap in the settings. For large selections, aggregate right in the query.
The exact limit values are configured in System → the JavaScript tab.
Read-only sql
The tagged template sql\SELECT …`runs a read-only data query within the owner's permissions. It is available **both in auto-pause rules (Britva) and in user scripts** — provided the corresponding system setting is enabled. In a browser test run it is disabled (likectx.fetch), so verify a sql`-using rule or script via a real run on the server.
The full list of tables and columns a query can reach is in Tables for sql queries.