Zernio
APIFor you
Zernio
APIFor you
API Reference

Campaigns and Ads

Overview

Get campaign treeGETGet daily account metricsGET

Campaigns

List campaignsGETCreate a standalone campaignPOSTGet live campaign detailsGETUpdate a campaignPUTDuplicate a campaignPOSTDelete a campaignDELETEPause or resume a campaignPUTPause or resume many campaignsPOSTList campaign assetsGETAttach campaign assetsPOSTUpdate campaign assetsPUTRemove campaign assetsDELETERead a Google campaign's device, location, excluded location, and language targetingGETEdit a Google campaign's device, location, excluded location, or language targetingPUTRead a campaign's ad schedule (dayparting)GETReplace a campaign's ad schedule (dayparting)PUTGet campaign conversion goalsGETUpdate campaign conversion goalsPATCH

Asset Groups

List Performance Max asset groupsGETCreate a Performance Max asset groupPOSTGet a Performance Max asset groupGETUpdate a Performance Max asset groupPATCHRemove a Performance Max asset groupDELETELink or unlink asset group assetsPOSTReplace an asset group's listing-group treePUT

Ad Sets

List ad setsGETCreate a standalone ad groupPOSTGet live ad-set detailsGETUpdate an ad setPUTDuplicate an ad setPOSTDelete an ad setDELETEPause or resume a single ad setPUTList ad-group assetsGETAttach ad-group assetsPOSTUpdate ad-group assetsPUTRemove ad-group assetsDELETE

Ads

List adsGETGet ad detailsGETCreate standalone adPOSTBoost post as adPOSTUpdate adPUTDuplicate an adPOSTCancel an adDELETEPause or resume a single adPUT

Keywords

List Search keywordsGETAdd Search ad-group keywordsPOSTPause or enable a Search keywordPATCHRemove a Search keywordDELETEList campaign-level negative keywordsGETReplace campaign-level negative keywordsPUTList campaign negative listsGETReplace campaign negative listsPUT

Bidding

Read a campaign's current biddingGETList portfolio bid strategiesGETCreate portfolio bid strategyPOSTUpdate portfolio bid strategyPATCH

Recommendations

List Google Ads recommendationsGETApply Google Ads recommendationsPOSTDismiss Google Ads recommendationsPOST

Other

Create a shared budgetPOSTRead the platform's review verdict for an adGETReview status of each creative in a TikTok Smart+ adGETList shared budgetsGETReview status of every TikTok Smart+ ad of an advertiserGET
Dashboard
OverviewPlatformsAPI ReferenceResources
Campaigns and Ads

List ads

Lists your ads with their performance over a date range, including ads created directly in each platform's ads manager.

Returns a paginated list of ads with metrics computed over an optional date range. Use source=all to include externally-synced ads from platform ad managers. If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.

History: when an ad account connects, Zernio imports its last 90 days of metrics, so the metrics hold no data for days before that. When accountId or adAccountId resolves to a Meta ad account, a range reaching further back answers 202 with backfillPending: true and the covered part while the older days (up to 730 days back) are imported in the background; repeat the request until it returns 200. A request scoped to no Meta account never returns 202.

To find the Zernio ad behind a comment you see in Meta Business Manager, filter by platformAdId (the Meta ad ID), effectiveObjectStoryId (Facebook), or effectiveInstagramMediaId (Instagram). Those are the post/media the ad's engagement lives on, and are also returned on each ad's creative object. Then call GET /v1/ads/{adId}/comments with the returned ad id.

PlatformsMetaGoogleTikTokLinkedInPinterestX
GET
/v1/ads

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Query Parameters

page?integer

Page number (1-based)

Range1 <= value
Default1
limit?integer
Range1 <= value <= 500
Default50
source?string

all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only.

Default"all"

Value in

  • "zernio"
  • "all"
status?string

Value in

  • "active"
  • "paused"
  • "pending_review"
  • "rejected"
  • "completed"
  • "cancelled"
  • "error"
platform?string

Value in

  • "facebook"
  • "instagram"
  • "tiktok"
  • "linkedin"
  • "pinterest"
  • "google"
  • "twitter"
  • "openai"
  • "reddit"
accountId?string

Account ID

adAccountId?string

Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.

pageId?string

Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). Matches each ad's creative.pageId; ads with no page signal (rare IG-only creatives) never match. Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.

profileId?string

Profile ID

campaignId?string

Platform campaign ID (filter ads within a campaign)

adSetId?string

Platform ad set ID (filter ads within an ad set, the /{adset_id}/ads read of an adset-centric dashboard).

platformAdId?string

Meta ad ID. Returns the ad with this platform-side ad ID.

effectiveObjectStoryId?string

Facebook {pageId}_{postId} of the post the ad's engagement lives on (Meta effective_object_story_id). Use to map a Business-Manager-visible post back to the Zernio ad.

effectiveInstagramMediaId?string

Instagram media ID of the boosted post (Meta effective_instagram_media_id). Use to map a Business-Manager-visible IG post back to the Zernio ad.

fromDate?string

Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.

Formatdate
toDate?string

End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.

Formatdate

Response Body

application/json

application/json

application/json

application/json

import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.adcampaigns.listAds();console.log(data);
{  "ads": [    {      "_id": "string",      "name": "string",      "platform": "facebook",      "profileId": "string",      "status": "active",      "configuredStatus": "string",      "reviewStatus": "in_review",      "adType": "boost",      "creativeType": "carousel",      "goal": "engagement",      "isExternal": true,      "budget": {        "amount": 0,        "type": "daily",        "daily": 0,        "lifetime": 0,        "pacing": "string"      },      "metrics": {        "spend": 0,        "impressions": 0,        "reach": 0,        "clicks": 0,        "ctr": 0,        "cpc": 0,        "cpm": 0,        "engagement": 0,        "conversions": 0,        "allConversions": 0,        "costPerConversion": 0,        "actions": {          "property1": 0,          "property2": 0        },        "actionValues": {          "property1": 0,          "property2": 0        },        "purchaseValue": 0,        "roas": 0,        "costPerAction": {          "property1": 0,          "property2": 0        },        "outboundClicks": 0,        "outboundClicksCtr": 0,        "inlineLinkClicks": 0,        "inlineLinkClickCtr": 0,        "uniqueClicks": 0,        "uniqueCtr": 0,        "videoPlayActions": 0,        "video30SecWatchedActions": 0,        "videoThruplayWatchedActions": 0,        "videoP25WatchedActions": 0,        "videoP50WatchedActions": 0,        "videoP75WatchedActions": 0,        "videoP95WatchedActions": 0,        "videoP100WatchedActions": 0,        "video2SecWatchedActions": 0,        "video6SecWatchedActions": 0,        "video6SecFocusedViews": 0,        "videoAvgTimeWatchedActions": 0,        "costPerThruplay": 0,        "funnel": {          "landingPageViews": 0,          "contentViews": 0,          "searches": 0,          "wishlistAdds": 0,          "cartAdds": 0,          "checkoutsInitiated": 0,          "paymentInfoAdds": 0,          "purchases": 0,          "leads": 0,          "registrationsCompleted": 0,          "appInstalls": 0,          "messagingConversationsStarted": 0,          "messagingFirstReplies": 0        },        "engagementBreakdown": {          "postEngagement": 0,          "pageEngagement": 0,          "reactions": 0,          "comments": 0,          "shares": 0,          "saves": 0,          "pageLikes": 0,          "videoViews": 0,          "linkClicks": 0        },        "lastSyncedAt": "2019-08-24T14:15:22Z"      },      "platformAdId": "string",      "platformAdAccountId": "string",      "platformCampaignId": "string",      "platformAdSetId": "string",      "campaignName": "string",      "adSetName": "string",      "platformObjective": "string",      "optimizationGoal": "string",      "costType": "string",      "servingStatuses": [        "string"      ],      "platformAdAccountName": "string",      "platformCreatedAt": "2019-08-24T14:15:22Z",      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",      "bidAmount": 0,      "roasAverageFloor": 0,      "promotedObject": {        "custom_event_type": "string",        "pixel_id": "string",        "page_id": "string",        "application_id": "string",        "product_set_id": "string"      },      "creative": {        "assetGroup": {          "name": "string",          "finalUrl": "http://example.com",          "headlines": [            "string",            "string",            "string"          ],          "longHeadline": "string",          "descriptions": [            "string",            "string"          ],          "businessName": "string",          "images": {            "landscape": [              "http://example.com"            ],            "square": [              "http://example.com"            ],            "logo": [              "http://example.com"            ]          },          "youtubeVideoId": "string"        },        "assetGroupResourceName": "string",        "headlines": [          {            "text": "string",            "pinnedField": "HEADLINE_1"          },          {            "text": "string",            "pinnedField": "HEADLINE_1"          },          {            "text": "string",            "pinnedField": "HEADLINE_1"          }        ],        "descriptions": [          {            "text": "string",            "pinnedField": "DESCRIPTION_1"          },          {            "text": "string",            "pinnedField": "DESCRIPTION_1"          }        ],        "finalUrls": [          "http://example.com"        ],        "thumbnailUrl": "string",        "imageUrl": "string",        "assetResourceName": "string",        "assets": {          "marketingImages": [            {              "resourceName": "string"            }          ],          "squareMarketingImages": [            {              "resourceName": "string"            }          ]        },        "videoId": "string",        "videoUrl": "string",        "creativeId": "string",        "creativeFeatures": {          "property1": "OPT_IN",          "property2": "OPT_IN"        },        "catalog": {          "productSetId": "string",          "format": "single_image",          "formatTransformationSpec": [            {              "format": "string",              "data_source": [                "string"              ]            }          ]        },        "objectType": "string",        "objectStoryId": "string",        "effectiveObjectStoryId": "string",        "pageId": "string",        "effectiveInstagramMediaId": "string",        "instagramUserId": "string",        "instagramPermalinkUrl": "string",        "mediaUrls": [          "string"        ],        "carouselCards": [          {            "imageUrl": "string",            "imageHash": "string",            "headline": "string",            "description": "string",            "linkUrl": "string",            "callToAction": "string",            "videoId": "string"          }        ],        "isServing": true,        "adFormat": "string",        "servingHoldReasons": [          "string"        ],        "body": "string",        "googleHeadline": "string",        "googleDescription": "string",        "youtubeVideoIds": [          "string"        ],        "linkUrl": "string",        "whatsappPhoneNumber": "string",        "pinterestImageUrl": "string",        "pinterestTitle": "string",        "pinterestDescription": "string"      },      "targeting": {},      "schedule": {        "startDate": "2019-08-24T14:15:22Z",        "endDate": "2019-08-24T14:15:22Z"      },      "rejectionReason": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "page": 0,    "limit": 0,    "total": 0,    "pages": 0  },  "backfillPending": true}
Was this page helpful?

Remove ad-group assets

Detaches assets from a Google ad group without deleting them, so they stay in the account and on anything else they are attached to. Google assets cannot be deleted. Other attachments remain. assetResourceNames is retained for compatibility. Fields go in the query string. A JSON body with the same fields is also accepted and, when sent, the query string is ignored.

Get ad details

Shows one ad with its creative, targeting, status and performance metrics. Google Search ads include current creative.headlines, creative.descriptions and creative.finalUrls, preserving pinnedField. Top-level cachedAt and stale report cache freshness. Google mutations invalidate this read. RSA enrichment requires a stored advertisingChannelType of SEARCH. Ads with an unknown or other channel return their stored details without a Google read. If RSA enrichment fails, the stored ad is returned with HTTP 200 and without cache metadata. The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad: - the Zernio internal `_id` (24-char hex) - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`) - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side) - the creative's `effective_instagram_media_id` (Instagram side) - an Instagram media id an ad comment arrived on (`comment.platformPostId` of a `comment.received` carrying `comment.ad.id`), including the extra media Meta creates for placement variants Any of these resolve to the same ad. Caller doesn't need a translation step. `creative.creativeFeatures` holds the stored requested settings, which do not confirm platform application. **Facebook ad dark posts.** Meta gives an ad with per-placement assets one extra unpublished post per placement, and comments land on it. Meta exposes no link from that post to its ad. When exactly one ad on the Page, created before the dark post, carries the same copy as the post, the dark post id resolves to that ad. Otherwise, when the id is a dark post Zernio has seen comments on and its Page is connected, the response is `ad: null` plus `darkPost`, which carries the Meta Ads account and the ad accounts running ads for that Page. Read its comments with GET /v1/ads/{adId}/comments using the same id. **Status freshness.** `status`, `configuredStatus`, `platformStatus`, `platformAdSetStatus` and `platformCampaignStatus` are the values Zernio last stored. Background sync refreshes them, typically within 15 to 60 minutes (Google up to about 3 hours), and ended or long-paused objects may be refreshed less often. Zernio's own status writes re-read the switches they change. A change made in the platform's own ads manager therefore shows up here only after the next sync. Controllers that act on a switch should pass `live=true`, which reads the switches from the platform now, stores them, and returns `statusReadAt` (null when the read failed and the stored values were returned). With `live=true` the ad's own switch (`configuredStatus`), its delivery status (`status`, `platformStatus`) and its ad set and campaign switches (`platformAdSetStatus`, `platformCampaignStatus`) are read live.