Execution history and audit

Last updated: May 19, 2026

Execution history and audit

/rules/:id. Backed by GET /api/v1/rules/:id/executions (verified, paginated). Every cron fire of a rule writes to the automation_rule_execution table with full per-entity outcomes. Audit log entries (action: rule_create / update / delete / toggle / duplicate) live separately in audit_log table. Use both to answer "what did this rule do and when?".

Who is this for

Rule owners auditing what rules actually did. Anyone debugging "why did this campaign get paused yesterday?". Admins on compliance reviews.

How to view

Per-rule execution timeline

  1. Open /rules/:id

  2. Scroll to Executions section

  3. Timeline shows fires in reverse-chronological order

  4. Click a fire → expanded view per entity

Per-rule audit log

Same page → Audit tab. Shows lifecycle entries: who created / edited / paused / duplicated the rule and when.

What's in an execution record

automation_rule_execution schema fields:

  • id

  • rule_id

  • status — succeeded / partial_success / failed

  • entities_evaluated — total scanned

  • entities_matched — passed all conditions

  • entities_acted — action successfully applied

  • entities_skipped — matched but skipped by a protection

  • entities_errored — execution failed (API error / validation)

  • details (JSON) — per-entity result map

  • error_message — top-level failure (e.g. SQS timeout)

  • started_at, completed_at, duration_ms

  • metrics_snapshot (JSON) — the metric values used for evaluation

Reading the details

For each entity in details:

{
  "entity_id": "120211211211",
  "entity_name": "Adset Prospecting US v3",
  "matched": true,
  "metric_values": {"roas": 1.2, "spend": 120},
  "action_applied": "pause",
  "before": {"status": "active"},
  "after": {"status": "paused"},
  "skipped": false
}

Skipped entries include skip_reason:

  • cooldown_active

  • daily_cap_reached

  • pending_action_exists

  • budget_cap_reached

  • entity_state_conflict

Errored entries include error_message + attempt_count.

metrics_snapshot

A JSON object of the metric values seen at evaluation time. Useful when:

  • Investigating "the dashboard shows ROAS 2.5 now — why did the rule pause the adset?" → check snapshot; rule saw ROAS 0.8 at fire time, late conversions raised it

  • Debugging condition logic — did the metric actually match?

Audit log entries

audit_log table records each rule lifecycle action:

action

when

rule_create

new rule saved

rule_update

edits to existing rule

rule_delete

rule deleted

rule_toggle

pause ↔ active toggle

rule_duplicate

clone via POST /api/v1/rules/:id/duplicate

rule_execution_fired

each successful execution

Each entry: user_id, metadata (rule_id, change summary), ip_address, user_agent, product, created_at.

Access via /api/v1/audit-logs?resource_type=rule&resource_id={rule_id} or workspace-wide audit view.

Filtering + searching executions

Executions endpoint supports pagination + filters:

  • from_date / to_date

  • status (succeeded / failed / partial)

  • min_entities_acted — only fires that did something

  • Pagination: limit (1-100, default 50), offset

Endpoint

GET /api/v1/rules/:id/executions (verified apps/backend/src/routes/api/rules.route.ts).

Returns paginated executions matching filter criteria.

Use cases

Why did this adset pause yesterday?

  1. Open the adset in Ads Manager → see status changed at 14:35

  2. Go to /rules → find the rule that matches the adset's scope

  3. Open /rules/:id → executions around 14:30-14:40

  4. Find the entity in details → see metric_values + match details

  5. Validate the rule did the right thing (or fix the rule if not)

Did the new template actually act?

  1. After activating a templated rule, check executions over 24h

  2. entities_acted > 0 confirms the rule fired action

  3. entities_skipped reasons tell you about protection behavior

Compliance audit (90-day window)

  1. /api/v1/audit-logs?resource_type=rule&from_date=...&to_date=...

  2. Returns all rule lifecycle actions in window with user attribution

  3. Export for compliance review

Retention

Execution history retained per workspace plan tier — see /settings/team/billing. Audit log retention typically matches (or exceeds) execution retention.

Common mistakes

  • Looking at the dashboard instead of metrics_snapshot: dashboard is current; snapshot is what the rule saw. They can differ.

  • Confusing entities_matched with entities_acted: matched = passed conditions; acted = action actually applied (skip protections aside).

  • Missing audit log permission: audit log access may be admin-only depending on workspace policy.

Related