---
title: "List an ad rule's runs"
method: GET
path: "/v1/ads/rules/{ruleId}/runs"
tags: ["Ad Rules"]
---

# List an ad rule's runs

`GET /v1/ads/rules/{ruleId}/runs`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/ads/rules/{ruleId}/runs`
- Auth: HTTP bearer

Lists a rule's scheduled runs, newest first: what each run evaluated, matched and did.
Runs that changed something (or tried to) are kept permanently, also after the rule is deleted; runs that changed nothing are dropped after about 31 days.
For every change across all rules, use `GET /v1/ads/rules/activity`.

## Path parameters

- `ruleId` string, required

## Query parameters

- `limit` integer
- `skip` integer

## Response `200`

Runs

- object
  - `runs` AdRuleRun[], required
    - `id` string, required
    - `ranAt` string, date-time, required
    - `outcome` 'triggered' | 'cooldown' | 'no_match' | 'failed', required: Result of the rule run: - `triggered`: the rule acted on at least one object (`error` is set if the webhook could not be sent afterwards). - `cooldown`: objects matched but all were in cooldown. - `no_match`: nothing matched. - `failed`: the metrics could not be read, every action failed, or the webhook of a notify-only rule could not be sent (see `error`).
    - `objectsEvaluated` integer, required
    - `actedObjectIds` string[], required
    - `evaluation` object, nullable, required: The matched objects with their condition values, and what each action did.
      - `rule` object: The rule as it was when this run happened, so its actions stay readable after the rule is renamed or deleted. Absent on runs recorded before October 2026.
        - `name` string
        - `profileId` string
        - `accountId` string
        - `platform` string
        - `platformAdAccountId` string
        - `level` 'campaign' | 'adset'
      - `today` string, date
      - `timezone` string
      - `timezoneAssumed` boolean
      - `currency` string, nullable
      - `matched` AdRuleObjectEvaluation[]
        - `id` string, required: Platform ID of the campaign or ad set.
        - `name` string, required
        - `campaignId` string, nullable, required
        - `matched` boolean, required: True when every condition holds.
        - `conditions` object[], required
          - `metric` union, required: `ctr` is a percentage. `spend`, `cpc`, `cpm` and `cpa` are in the ad account currency. `reach` and `frequency` use the platform's de-duplicated reach, so they are accepted on Meta and TikTok only. `result:<key>` reads one of your own results (see [Campaign results](/guides/campaign-results)), on campaign rules only: the values you sent for the window, or a formula over them and the platform's numbers. A campaign with no value for it never matches.
            - 'spend' | 'impressions' | 'clicks' | 'conversions' | 'ctr' | 'cpc' | 'cpm' | 'cpa' | 'roas' | 'reach' | 'frequency'
            - string
          - `window` 'today' | 'yesterday' | 'last_3d' | 'last_7d' | 'last_14d' | 'last_30d', required: Days in the ad account's own timezone. `last_7d` is the 7 full days before today; only `today` reads the day in progress.
          - `op` '>' | '>=' | '<' | '<=', required
          - `value` number, required
          - `actual` number, nullable, required: The object's value over the window. Null when it cannot be computed.
          - `met` boolean, required
      - `actions` object[]
        - `objectId` string, required
        - `type` 'pause' | 'activate' | 'adjust_budget', required
        - `status` 'done' | 'skipped' | 'failed', required
        - `reason` string: Why it was skipped or failed, for example `already_paused`.
        - `previousDailyBudget` number
        - `newDailyBudget` number
      - `notification` object: Set when a run of a rule with a `notify` action matched objects and tried to send the webhook. A notify-only rule whose webhook fails ends with outcome `failed`. - `done`: the `ad_rule.triggered` webhook is queued for the webhooks subscribed to it (with none subscribed it is still `done`, but nothing is delivered). - `failed`: it could not be queued.
        - `status` 'done' | 'failed', required
        - `reason` string: Why the webhook could not be queued.
    - `error` string, nullable, required

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `403`: Ads access required (code `ads_addon_required`). Legacy plans need the Ads add-on; included by default on usage-based plans.
- `404`: Resource not found

## Changes

- **2026-10-30** `c319eb5d95b6`: 12 info
  - added `subschema #1, subschema #2` to the `runs/items/evaluation/matched/items/conditions/items/allOf[#/components/schemas/AdRuleCondition]/metric` response property `anyOf` list for the response status `200`
  - removed the `clicks` enum value from the `runs/items/evaluation/matched/items/conditions/items/allOf[#/components/schemas/AdRuleCondition]/metric` response property for the response status `200`
  - removed the `conversions` enum value from the `runs/items/evaluation/matched/items/conditions/items/allOf[#/components/schemas/AdRuleCondition]/metric` response property for the response status `200`
  - removed the `cpa` enum value from the `runs/items/evaluation/matched/items/conditions/items/allOf[#/components/schemas/AdRuleCondition]/metric` response property for the response status `200`
  - …8 more
- **2026-10-30** `f239e5073e14`: 2 warning
  - added the new `frequency` enum value to the `runs/items/evaluation/matched/items/conditions/items/allOf[#/components/schemas/AdRuleCondition]/metric` response property for the response status `200`
  - added the new `reach` enum value to the `runs/items/evaluation/matched/items/conditions/items/allOf[#/components/schemas/AdRuleCondition]/metric` response property for the response status `200`
- **2026-10-28** `6c6734610625`: 1 info
  - added the optional property `runs/items/evaluation/rule` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/rules/:ruleId/runs/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/c319eb5d95b6?raw)