List ad rules
Lists the ad rules on the profiles your key can reach, newest first.
Authentication
API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.
Query parameters
OptionalOnly rules on this ads connection.
Only rules watching this platform ad account.
500Responses
Success· the request worked
Errors· the request failed
Flexible live insights query
Runs a custom performance query against Meta, Google Ads or TikTok and returns the platform's rows as is, for reports the fixed endpoints don't cover. The account's platform picks the contract. ### Meta (facebook/instagram) Forwards caller-chosen `fields`, `breakdowns` and `filtering` to any Meta insights node and returns Meta's rows verbatim. - `objectId` (required) selects the node. - `level` sets row granularity. Semantic validation is Meta's: an unknown field or invalid breakdown combination returns a 400 carrying Meta's message. For long ranges or agency-scale accounts, prefer the async variant (POST /v1/ads/insights/reports). ### Google Ads (googleads) Raw GAQL passthrough. Send any read-only GAQL SELECT via `query` (campaign/keyword/search-term/geo/demographic/asset/shopping resources, `change_event`, any `segments.*`). Rows come back verbatim (camelCase, counters as strings). - Results are paged at a fixed 10,000 rows; follow `paging.nextPageToken` with `pageToken`. - `adAccountId` (alias `customerId`) is only needed when the connection has several Google Ads accounts. Semantic validation is Google's: an invalid query returns a 400 carrying Google's message (note: selecting `segments.date` requires a finite date filter). #### GAQL version Queries run against Google Ads API **v25**, so write GAQL against the v25 field reference. One exception is translated for backward compatibility: - The legacy `campaign.start_date` / `campaign.end_date` (removed by Google in v23) are rewritten to `campaign.start_date_time` / `campaign.end_date_time`. - Rows still carry `campaign.startDate` / `campaign.endDate` as `YYYY-MM-DD`. - In WHERE, `=`, `<`, `<=`, `>`, `>=`, `BETWEEN` and `IS [NOT] NULL` against a `'YYYY-MM-DD'` literal are translated; any other form returns Google's 400. New code should select the `_date_time` fields directly. ### TikTok (tiktok/tiktokads) Passthrough of TikTok's synchronous report (`/report/integrated/get/`). Send: - `adAccountId` - `dataLevel` - `dimensions` - `metrics` - `fromDate`/`toDate` (TikTok caps the span at 365 days) - optionally `filtering`, in the same `[{"field", "operator", "value"}]` shape as Meta (operator is TikTok's `filter_type`, e.g. `IN`; array values are JSON-encoded for TikTok) Rows come back verbatim as `{ dimensions, metrics }` with page-number paging. #### De-duplicated reach across a set of campaigns, ad groups or ads Filter the set and group by `country_code` instead of the entity id. TikTok then counts each person once across the whole set and range, per country. Example, two campaigns for a month: `dataLevel=AUCTION_CAMPAIGN&dimensions=country_code&metrics=reach,impressions,frequency&fromDate=2026-09-01&toDate=2026-09-30&filtering=[{"field":"campaign_ids","operator":"IN","value":["1876574798182050","1876575504573650"]}]` - For a set of ads use `dataLevel=AUCTION_AD` with `ad_ids`. - A filter on a finer entity than `dataLevel` (e.g. `ad_ids` at `AUCTION_CAMPAIGN`) returns 400: TikTok would otherwise widen it to every parent entity containing those ids. - `AUCTION_ADVERTISER` rejects entity filters. When the set delivers in several countries, reach is per country: summing the rows counts a person reached in two countries twice.
Create an ad rule
Creates a rule that checks the campaigns or ad sets of one ad account on a schedule and acts on each one that meets every condition. Rules support Meta, Google, TikTok, LinkedIn, Pinterest, X and Reddit ads connections. Use `POST /v1/ads/rules/{ruleId}/preview` to see what a rule would match before enabling it. ### Evaluation Each campaign or ad set is evaluated on its own, over the ad account's calendar days, from the metrics Zernio syncs. ### Actions A rule can notify (the `ad_rule.triggered` webhook), and take at most one of: - `pause` - `activate` - `adjust_budget` ### Cooldown After acting on an object, the rule leaves that object alone for `cooldownMinutes`. A rule that pauses, activates or adjusts budgets needs a cooldown at least as long as its schedule. ### How `activate` works `activate` only reactivates objects a rule paused, never ones you paused yourself, and only once the cooldown has passed since that pause. If you reactivate and pause such an object yourself between two runs of a rule, Zernio cannot tell your pause from the rule's, and an `activate` rule may reactivate it.