Automated ad rules

An ad rule watches one ad account for you. On a schedule, it checks every campaign, ad set or ad against a set of conditions ("cost per conversion above 25 over the last 7 days") and acts on each one that matches: pause it, turn it back on, change its daily budget, or send you an ad_rule.triggered webhook. Rules run on Meta, Google, TikTok, LinkedIn, Pinterest, X and Reddit.

#Create a rule safely

curl -X POST https://api.pozy.ai/v1/ads/rules \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pause expensive ad sets",
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "adAccountId": "act_1234567890",
    "level": "adset",
    "conditions": { "all": [
      { "metric": "cpa", "window": "last_7d", "op": ">", "value": 25 },
      { "metric": "spend", "window": "last_7d", "op": ">=", "value": 50 }
    ] },
    "actions": [{ "type": "pause", "maxChangesPerDay": 10 }, { "type": "notify" }],
    "schedule": { "everyMinutes": 60 },
    "cooldownMinutes": 1440,
    "enabled": false
  }'

const res = await fetch("https://api.pozy.ai/v1/ads/rules", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Pause expensive ad sets",
    accountId: "66b2e19d8c3f5a7e9d0b1c2d",
    adAccountId: "act_1234567890",
    level: "adset",
    conditions: {
      all: [
        { metric: "cpa", window: "last_7d", op: ">", value: 25 },
        { metric: "spend", window: "last_7d", op: ">=", value: 50 },
      ],
    },
    actions: [{ type: "pause", maxChangesPerDay: 10 }, { type: "notify" }],
    schedule: { everyMinutes: 60 },
    cooldownMinutes: 1440,
    enabled: false,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.rule.id);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/ads/rules",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "name": "Pause expensive ad sets",
        "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
        "adAccountId": "act_1234567890",
        "level": "adset",
        "conditions": {"all": [
            {"metric": "cpa", "window": "last_7d", "op": ">", "value": 25},
            {"metric": "spend", "window": "last_7d", "op": ">=", "value": 50},
        ]},
        "actions": [{"type": "pause", "maxChangesPerDay": 10}, {"type": "notify"}],
        "schedule": {"everyMinutes": 60},
        "cooldownMinutes": 1440,
        "enabled": False,
    },
)
print(resp.json()["rule"]["id"])

curl -X POST https://api.pozy.ai/v1/ads/rules/66f9a0b1c2d3e4f5a6b7c8d9/preview \
  -H "Authorization: Bearer $POZY_API_KEY"

{
  "evaluatedAt": "2026-10-30T09:00:00.000Z",
  "today": "2026-10-30",
  "timezone": "America/New_York",
  "timezoneAssumed": false,
  "currency": "USD",
  "matched": 1,
  "objects": [
    { "id": "120210000000000001", "name": "Retargeting, 7 day", "campaignId": "120210000000000000", "matched": true, "conditions": [ { "metric": "cpa", "actual": 31.4 }, { "metric": "spend", "actual": 188.2 } ] }
  ]
}

curl -X PATCH https://api.pozy.ai/v1/ads/rules/66f9a0b1c2d3e4f5a6b7c8d9 \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

#Rule fields

#Conditions

Each condition checks one metric, measured over one time window, against a threshold:

{ "metric": "roas", "window": "last_3d", "op": "<", "value": 1.5 }

• Metrics: spend, impressions, clicks, conversions, cpc, cpm, cpa, roas, reach, frequency, and ctr as a percentage.
• Windows: today, yesterday, last_3d, last_7d, last_14d, last_30d. A day is a day in the ad account's time zone, and the multi-day windows count today.
• Operators: >, >=, <, <=.
• reach and frequency need de-duplicated reach, which only Meta and TikTok provide. On other networks they return 400.
• A rate with nothing to divide by never matches. A cpa condition skips objects with no conversions, so pair it with a spend floor as in the example.

#Actions

Combine notify with no more than one changing action: pause, activate or adjust_budget. Those three accept maxChangesPerDay, from 1 to 100, which caps how many objects the rule may change in a rolling 24 hours, counting all its runs. Objects past the cap are skipped with daily_limit_reached and picked up on a later run. A rule that changes objects must also have a cooldownMinutes no shorter than its schedule.

#What a rule did

GET /v1/ads/rules/{ruleId}/runs shows a rule's runs over the past 31 days, latest first. For the workspace as a whole, GET /v1/ads/rules/activity lists each change that any rule made.

Each run's evaluation.actions[] records status (done, skipped or failed) per object, with a reason on skips and previousDailyBudget and newDailyBudget on budget changes. evaluation.notification.status is done once the webhook is queued.

#The webhook

ad_rule.triggered fires when a run of a rule with a notify action acts on at least one object.

• objects[] lists only the objects the run acted on. Objects in cooldown are left out, and a run where every match is resting sends nothing.
• objects[].conditions holds every condition again, with actual set to the object's real value.
• objects[].actions records what the rule changed on the object; a rule that only notifies leaves it empty.
• run.today, run.timezone and run.currency tell you which calendar day and currency the numbers used. run.timezoneAssumed is true when the ad account has no known time zone and UTC was used.

The full payload is in the events reference.

#How rules behave

• Metrics lag. Rules read the metrics Pozy syncs from each network, which can trail the network's own dashboard.
• Batch size. A run changes 20 objects at most; any further matches are handled by the next run.
• Failed actions get no cooldown, so the next run retries them.
• Your own pauses. activate only restores what the rule paused. If you turn an object on and off again between two runs, the rule cannot tell your pause from its own.
• Google budgets live on campaigns, so adjust_budget on Google needs level: "campaign".
• Ads access. If the workspace loses ads access, every rule pauses until it returns.
• Free allowance. Past the free allowance of live ads without a payment method, reactivations and budget increases are skipped with ads_allowance_exceeded. Pauses and decreases keep working.
• Disabled rules stop running until you set enabled: true again. DELETE /v1/ads/rules/{ruleId} removes a rule for good.

#Errors you will see

#Endpoints

#Webhook events