Pause and resume rules

Per-rule toggle: POST /api/v1/rules/:id/toggle flips between paused and active. Or use the rule's action menu → Pause / Resume. Rules in status: error (circuit-breaker tripped) require manual review of last_error before resume. Paused rules keep all history.

Who is this for

Anyone managing rules day-to-day. Common during creative refreshes, holiday closures, post-incident debugging.

The three statuses

Per-rule toggle

From the rule list

/rules → row actions menu → Pause / Resume.

From the rule detail

/rules/:id → top toolbar → Pause / Resume.

Via API

POST /api/v1/rules/:id/toggle flips current status:

• paused → active

• active → paused

• error → requires explicit force flag or manual unwind (see Error recovery below)

Returns the updated rule.

What happens on pause

• status → paused

• No further cron evaluations

• In-flight executions complete (no cancel)

• Execution history preserved

• Notifications stop (notify_on_execution only fires on action)

• last_evaluated_at preserved

What happens on resume

• status → active

• Next cron tick (within 15 min) evaluates the rule

• last_evaluated_at checked normally — if rule was paused for hours, it resumes at next cycle (not catching up)

• Cooldowns: per-entity cooldowns from the past still apply if still within window

Error recovery

When a rule auto-pauses to status: error via the circuit breaker (see rul-108):

Step 1: Review last_error

/rules/:id shows last_error (last error message that contributed to circuit-breaker trip).

Common errors:

• platform_token_expired — ad account token revoked / expired

• platform_api_error: ... — upstream API issue (transient or permanent)

• validation_error: budget below minimum — action params became invalid

• network_error — transient infrastructure

Step 2: Fix the root cause

Per error:

• Token issues → re-authorize the ad account (/connect/{platform})

• Permanent API issues (e.g. platform deprecated an endpoint) → update the rule's action / metric

• Budget validation → adjust the rule's pct value or scope

• Transient → wait, then retry

Step 3: Resume

Manual toggle: /rules/:id → Resume. Sets status: active and clears auto_pause_reason.

If you resume without fixing: the rule will re-trip the circuit breaker within hours.

Step 4: Monitor first 24h

Watch execution history. If errors persist: pause + re-investigate.

cb_reset_after — automatic resume eligibility

When the circuit breaker trips, cb_reset_after is set to a future timestamp. After this time, the rule may auto-resume on the next cron tick if error rate is no longer above threshold.

For most cases: don't rely on auto-resume. Fix the cause + manually resume earlier.

Use cases

Creative refresh week

Active campaigns are being rebuilt; many entities will be paused / archived. Pause the kill-loser rules to avoid acting on the temporary state. Resume after rebuild.

Time-bound campaign window

Holiday-only rule (e.g. "Black Friday spend cap"): pause outside the window, resume in early November, pause in early December.

Hand-over to colleague

Pause rules you maintained, until handover meeting + new owner reviews + resumes.

Post-incident audit

After an incident: pause all rules → analyze execution history → identify which rule caused the issue → fix that one → resume others.

Bulk pause / resume

For 5+ rules at once: use bulk edit instead.

Audit log

Each toggle writes an entry:

• action: rule_toggle

• metadata: from: paused, to: active (or vice versa) + triggered_by: manual or triggered_by: circuit_breaker

Visible in /api/v1/audit-logs?resource_type=rule&action=rule_toggle.

Common mistakes

• Resuming error-status without fixing: re-trips circuit breaker within hours

• Pausing instead of editing: if a rule is wrong, pause is temporary; edit + activate is the fix

• Forgetting paused rules: they're invisible to "what's running" mental model. Periodically review /rules?status=paused and decide: resume or delete.

• Expecting paused rules to "catch up" on resume: they don't — resume picks up at next cron tick, no replay

Related

• Bulk edit rules — multi-rule alternative

• Protections + cooldown — circuit breaker mechanics

• Troubleshooting — debugging error status