Zernio
Zernio
API Reference

Campaigns and Ads

Overview

Get campaign treeGETGet daily account metricsGET

Campaigns

List campaignsGETCreate a standalone campaignPOSTUpdate a campaignPUTDuplicate a campaignPOSTDelete a campaignDELETEPause or resume a campaignPUTPause or resume many campaignsPOSTAttach extension assets to a Google Search campaignPOST

Ad Sets

Live ad-set details incl. learning phaseGETUpdate an ad setPUTDuplicate an ad setPOSTDelete an ad setDELETEPause or resume a single ad setPUTList Search keywordsGET

Ads

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

Other

Add Search keywords to an ad groupPOSTCreate a standalone ad groupPOSTCreate a Google Ads portfolio bid strategyPOSTRead a campaign's current biddingGETRead a Google campaign's device, location, and language targetingGETList ad setsGETList Google Ads portfolio bid strategiesGETList campaign-level negative keywordsGETRemove a Search keywordDELETEReplace campaign-level negative keywordsPUTPause or enable a Search keywordPATCHUpdate a Google Ads portfolio bid strategyPATCHEdit a Google campaign's device, location, or language targetingPUT
Dashboard
llms.txtOpenAPI
OverviewPlatformsAPI ReferenceResources
Campaigns and Ads

List ads

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.

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 - use your Zernio API key as a Bearer token

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"
accountId?string

Social 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

{  "ads": [    {      "_id": "string",      "name": "string",      "platform": "facebook",      "status": "active",      "configuredStatus": "string",      "reviewStatus": "in_review",      "adType": "boost",      "creativeType": "carousel",      "goal": "engagement",      "isExternal": true,      "budget": {        "amount": 0,        "type": "daily"      },      "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,        "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": {        "thumbnailUrl": "string",        "imageUrl": "string",        "videoId": "string",        "videoUrl": "string",        "creativeId": "string",        "objectType": "string",        "objectStoryId": "string",        "effectiveObjectStoryId": "string",        "pageId": "string",        "effectiveInstagramMediaId": "string",        "instagramUserId": "string",        "instagramPermalinkUrl": "string",        "mediaUrls": [          "string"        ],        "isServing": true,        "servingHoldReasons": [          "string"        ],        "body": "string",        "googleHeadline": "string",        "googleDescription": "string",        "linkUrl": "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?

List Search keywords

Returns the Google Search keyword criteria (positive and negative) synced from connected Google Ads accounts, one row per ad-group keyword. Refreshed about once a week per Google Ads customer (the keyword sweep rides the ads discovery pass on a slower slot, to stay inside Google's shared daily API quota), so keywords added on Google can take several days to appear. A customer synced for the first time is populated on the next discovery pass rather than waiting for its weekly slot, and connecting an account or triggering a manual sync refreshes it immediately. Campaign-level negative keywords are not included; only ad-group-level criteria are.

Get ad details

Returns an ad with its creative, targeting, status, and performance metrics. 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) Any of the four resolve to the same ad. Caller doesn't need a translation step.