Get ad analytics
Returns one ad's performance summary and daily timeline, with optional audience breakdowns on Meta, TikTok and LinkedIn.
Includes summary metrics, a daily timeline over the requested date range, and optional demographic breakdowns (Meta, TikTok and LinkedIn only). 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. summary
and daily come from those synced metrics, so they hold no data for days before that.
Breakdowns are read live from the platform over the requested range, so they are not limited
by the import.
When the ad belongs 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.
Other platforms never return 202.
Authorization
bearerAuth API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.
In: header
Path Parameters
Query Parameters
Start of date range (YYYY-MM-DD). Defaults to 90 days ago.
dateEnd of date range (YYYY-MM-DD). Defaults to today. Max 730-day range.
dateComma-separated breakdown dimensions.
Meta: age, gender, country, publisher_platform, device_platform, region, platform_position, impression_device, video_asset, image_asset, body_asset, title_asset.
TikTok: gender, age, country (or country_code), publisher_platform (or platform),
ac, language, placement. TikTok serves at most 365 days per breakdown, so a longer
range is read over its last 365 days and analytics.breakdownsRange says which window.
LinkedIn (firmographics): job_title, job_function, seniority, industry,
company, company_size, country, region. Rows carry the raw pivot value
plus a resolved name. LinkedIn serves these aggregated over the whole
range, delays the data 12-24h, and omits segments with fewer than 3 events.
A known dimension the platform cannot break down by is listed in
analytics.unsupportedBreakdowns instead of being dropped (with guidance in
analytics.breakdownHints where there is an alternative); the rest of the response
is unchanged. An unknown name returns 400. A TikTok dimension that fails is listed
in analytics.breakdownErrors and the response stays 200.
Metrics TikTok refuses for a dimension are listed in analytics.breakdownDroppedMetrics,
and the row values derived from them are null.
Response Body
application/json
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.adinsights.getAdAnalytics({ path: { adId: 'ad_abc123', },});console.log(data);{ "backfillPending": true, "ad": { "id": "string", "name": "string", "platform": "string", "status": "string", "currency": "string" }, "analytics": { "summary": { "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" }, "daily": [ { "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", "date": "2019-08-24" } ], "breakdowns": { "property1": [ {} ], "property2": [ {} ] }, "unsupportedBreakdowns": [ "string" ], "breakdownHints": { "property1": "string", "property2": "string" }, "breakdownErrors": [ { "breakdown": "string", "message": "string" } ], "breakdownDroppedMetrics": { "property1": [ "string" ], "property2": [ "string" ] }, "breakdownsRange": { "fromDate": "2019-08-24", "toDate": "2019-08-24" } }}Submit async insights report
Starts a background Meta insights report for long date ranges or large accounts where a live query would be too slow. Same query surface as GET /v1/ads/insights, but in the JSON body; Meta processes the report server-side, which is the right choice for long ranges or large accounts where the sync query is slow or rate-limited. Returns a `reportRunId` to poll via GET /v1/ads/insights/reports/{reportRunId}.
Poll an async insights report run
Checks progress of a background Meta insights report and returns its results once it has finished. Status and results for a report run created via POST /v1/ads/insights/reports. While the job runs, returns `status` and `percentCompletion`. Once `status` is "Job Completed" the response also carries a `data` page, cursor-paginated via `limit` / `after`.