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.
API key authentication - use your Zernio API key as a Bearer token
In: header
Query Parameters
Page number (1-based)
11 <= value501 <= value <= 500all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only.
"all""zernio" | "all""active" | "paused" | "pending_review" | "rejected" | "completed" | "cancelled" | "error""facebook" | "instagram" | "tiktok" | "linkedin" | "pinterest" | "google" | "twitter" | "openai"Social account ID
Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.
Profile ID
Platform campaign ID (filter ads within a campaign)
Meta ad ID. Returns the ad with this platform-side ad ID.
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.
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.
Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.
dateEnd of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
dateResponse Body
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",
"status": "active",
"configuredStatus": "ACTIVE",
"reviewStatus": "in_review",
"adType": "boost",
"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,
"costPerConversion": 0,
"actions": {
"link_click": 160,
"post_engagement": 300,
"offsite_conversion.fb_pixel_purchase": 42
},
"actionValues": {
"offsite_conversion.fb_pixel_purchase": 2456.78,
"offsite_conversion.fb_pixel_add_to_cart": 980.5
},
"purchaseValue": 0,
"roas": 0,
"videoPlayActions": 0,
"video30SecWatchedActions": 0,
"videoThruplayWatchedActions": 0,
"videoP25WatchedActions": 0,
"videoP50WatchedActions": 0,
"videoP75WatchedActions": 0,
"videoP95WatchedActions": 0,
"videoP100WatchedActions": 0,
"videoAvgTimeWatchedActions": 0,
"lastSyncedAt": "2019-08-24T14:15:22Z"
},
"platformAdId": "string",
"platformAdAccountId": "string",
"platformCampaignId": "string",
"platformAdSetId": "string",
"campaignName": "string",
"adSetName": "string",
"platformObjective": "OUTCOME_SALES",
"optimizationGoal": "OFFSITE_CONVERSIONS",
"platformAdAccountName": "Zernio - previously Late",
"platformCreatedAt": "2019-08-24T14:15:22Z",
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"bidAmount": 5,
"roasAverageFloor": 2,
"promotedObject": {
"custom_event_type": "PURCHASE",
"pixel_id": "string",
"page_id": "string",
"application_id": "string",
"product_set_id": "string"
},
"creative": {
"thumbnailUrl": "string",
"imageUrl": "string",
"videoId": "string",
"videoUrl": "string",
"objectType": "string",
"objectStoryId": "string",
"effectiveObjectStoryId": "string",
"effectiveInstagramMediaId": "string",
"instagramUserId": "string",
"instagramPermalinkUrl": "string",
"mediaUrls": [
"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"
}
],
"backfillPending": true,
"pagination": {
"page": 0,
"limit": 0,
"total": 0,
"pages": 0
}
}{
"error": "string",
"type": "invalid_request_error",
"code": "string",
"param": "string",
"platform": "string",
"platformError": {},
"details": {}
}{
"error": "Unauthorized"
}List campaigns GET
Returns campaigns as virtual aggregations over ad documents grouped by platform campaign ID. Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign. Campaign status is derived from child ad statuses (active > pending_review > paused > error > completed > cancelled > rejected).
Create a standalone campaign POST
Creates a campaign WITHOUT its first ad set / ad (the ODAX shell only). Ad sets join it later via `existingCampaignId` on the create endpoints. A budget here is campaign-level (CBO) by definition; omit it for ABO (each ad set carries its own budget). Created `PAUSED` unless `status: ACTIVE`. The campaign materializes in `/v1/ads/tree` via the next sync discovery pass.