Ads · Ad Insights

Get ad analytics

Fetches ad analytics.

GEThttps://api.pozy.ai/v1/ads/{adId}/analytics

Facebook and Instagram, Google Workspace, TikTok, LinkedIn, Pinterest and X and 1 moregetAdAnalytics

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the ads resource group disabled get 403 resource_group_disabled. Authentication

Path parameters

Name	Type	Notes
`adId`required	string

Query parameters

Name	Type	Notes
`fromDate`	string (date)
`toDate`	string (date)
`breakdowns`	string

Example

curl -X GET "https://api.pozy.ai/v1/ads/6f40fa2fb0a7e728dd1a73b7/analytics" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/ads/6f40fa2fb0a7e728dd1a73b7/analytics", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/ads/6f40fa2fb0a7e728dd1a73b7/analytics",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

backfillPendingboolean
adobject
- idstring
- namestring
- platformstring
- statusstring
- currencystring
  Can be null.
analyticsobject
8 child fields
- summaryobject
  38 child fields
  spendnumber
  impressionsinteger
  reachinteger
  clicksinteger
  ctrnumber
  cpcnumber
  cpmnumber
  engagementinteger
  conversionsnumber
  allConversionsnumber
  costPerConversionnumber
  actionsmap of integer
  actionValuesmap of number
  purchaseValuenumber
  roasnumber
  costPerActionmap of number
  outboundClicksinteger
  outboundClicksCtrnumber
  inlineLinkClicksinteger
  inlineLinkClickCtrnumber
  uniqueClicksinteger
  uniqueCtrnumber
  videoPlayActionsinteger
  video30SecWatchedActionsinteger
  videoThruplayWatchedActionsinteger
  videoP25WatchedActionsinteger
  videoP50WatchedActionsinteger
  videoP75WatchedActionsinteger
  videoP95WatchedActionsinteger
  videoP100WatchedActionsinteger
  video2SecWatchedActionsinteger
  video6SecWatchedActionsinteger
  video6SecFocusedViewsinteger
  videoAvgTimeWatchedActionsnumber
  costPerThruplaynumber
  funnelobject
  13 child fields
  landingPageViewsinteger
  contentViewsinteger
  searchesinteger
  wishlistAddsinteger
  cartAddsinteger
  checkoutsInitiatedinteger
  paymentInfoAddsinteger
  purchasesinteger
  leadsinteger
  registrationsCompletedinteger
  appInstallsinteger
  messagingConversationsStartedinteger
  messagingFirstRepliesinteger
  engagementBreakdownobject
  9 child fields
  postEngagementinteger
  pageEngagementinteger
  reactionsinteger
  commentsinteger
  sharesinteger
  savesinteger
  pageLikesinteger
  videoViewsinteger
  linkClicksinteger
  lastSyncedAtstring (date-time)
- dailyarray of object
  39 child fields
  spendnumber
  impressionsinteger
  reachinteger
  clicksinteger
  ctrnumber
  cpcnumber
  cpmnumber
  engagementinteger
  conversionsnumber
  allConversionsnumber
  costPerConversionnumber
  actionsmap of integer
  actionValuesmap of number
  purchaseValuenumber
  roasnumber
  costPerActionmap of number
  outboundClicksinteger
  outboundClicksCtrnumber
  inlineLinkClicksinteger
  inlineLinkClickCtrnumber
  uniqueClicksinteger
  uniqueCtrnumber
  videoPlayActionsinteger
  video30SecWatchedActionsinteger
  videoThruplayWatchedActionsinteger
  videoP25WatchedActionsinteger
  videoP50WatchedActionsinteger
  videoP75WatchedActionsinteger
  videoP95WatchedActionsinteger
  videoP100WatchedActionsinteger
  video2SecWatchedActionsinteger
  video6SecWatchedActionsinteger
  video6SecFocusedViewsinteger
  videoAvgTimeWatchedActionsnumber
  costPerThruplaynumber
  funnelobject
  13 child fields
  landingPageViewsinteger
  contentViewsinteger
  searchesinteger
  wishlistAddsinteger
  cartAddsinteger
  checkoutsInitiatedinteger
  paymentInfoAddsinteger
  purchasesinteger
  leadsinteger
  registrationsCompletedinteger
  appInstallsinteger
  messagingConversationsStartedinteger
  messagingFirstRepliesinteger
  engagementBreakdownobject
  9 child fields
  postEngagementinteger
  pageEngagementinteger
  reactionsinteger
  commentsinteger
  sharesinteger
  savesinteger
  pageLikesinteger
  videoViewsinteger
  linkClicksinteger
  lastSyncedAtstring (date-time)
  datestring (date)
- breakdownsmap of array of object
- unsupportedBreakdownsarray of string
- breakdownHintsmap of string
- breakdownErrorsarray of object
  2 child fields
  breakdownstring
  messagestring
- breakdownDroppedMetricsmap of array of string
- breakdownsRangeobject
  2 child fields
  fromDatestring (date)
  toDatestring (date)

200 response

{
  "backfillPending": true,
  "ad": {
    "id": "6bfebd43ddc270f6d2c56fc5",
    "name": "Acme",
    "platform": "instagram",
    "status": "active",
    "currency": "USD"
  },
  "analytics": {
    "summary": {
      "spend": 12.5,
      "impressions": 1,
      "reach": 1,
      "clicks": 1,
      "ctr": 12.5,
      "cpc": 12.5,
      "cpm": 12.5,
      "engagement": 1,
      "conversions": 12.5,
      "allConversions": 12.5,
      "costPerConversion": 12.5,
      "actions": {
        "key": 1
      },
      "actionValues": {
        "key": 12.5
      },
      "purchaseValue": 12.5,
      "roas": 12.5,
      "costPerAction": {
        "key": 12.5
      },
      "outboundClicks": 1,
      "outboundClicksCtr": 12.5,
      "inlineLinkClicks": 1,
      "inlineLinkClickCtr": 12.5,
      "uniqueClicks": 1,
      "uniqueCtr": 12.5,
      "videoPlayActions": 1,
      "video30SecWatchedActions": 1,
      "videoThruplayWatchedActions": 1,
      "videoP25WatchedActions": 1,
      "videoP50WatchedActions": 1,
      "videoP75WatchedActions": 1,
      "videoP95WatchedActions": 1,
      "videoP100WatchedActions": 1,
      "video2SecWatchedActions": 1,
      "video6SecWatchedActions": 1,
      "video6SecFocusedViews": 1,
      "videoAvgTimeWatchedActions": 12.5,
      "costPerThruplay": 12.5,
      "funnel": {
        "landingPageViews": 1,
        "contentViews": 1,
        "searches": 1,
        "wishlistAdds": 1,
        "cartAdds": 1,
        "checkoutsInitiated": 1,
        "paymentInfoAdds": 1,
        "purchases": 1,
        "leads": 1,
        "registrationsCompleted": 1,
        "appInstalls": 1,
        "messagingConversationsStarted": 1,
        "messagingFirstReplies": 1
      },
      "engagementBreakdown": {
        "postEngagement": 1,
        "pageEngagement": 1,
        "reactions": 1,
        "comments": 1,
        "shares": 1,
        "saves": 1,
        "pageLikes": 1,
        "videoViews": 1,
        "linkClicks": 1
      },
      "lastSyncedAt": "2026-10-02T09:00:00.000Z"
    },
    "daily": [
      {
        "spend": 12.5,
        "impressions": 1,
        "reach": 1,
        "clicks": 1,
        "ctr": 12.5,
        "cpc": 12.5,
        "cpm": 12.5,
        "engagement": 1,
        "conversions": 12.5,
        "allConversions": 12.5,
        "costPerConversion": 12.5,
        "actions": {
          "key": 1
        },
        "actionValues": {
          "key": 12.5
        },
        "purchaseValue": 12.5,
        "roas": 12.5,
        "costPerAction": {
          "key": 12.5
        },
        "outboundClicks": 1,
        "outboundClicksCtr": 12.5,
        "inlineLinkClicks": 1,
        "inlineLinkClickCtr": 12.5,
        "uniqueClicks": 1,
        "uniqueCtr": 12.5,
        "videoPlayActions": 1,
        "video30SecWatchedActions": 1,
        "videoThruplayWatchedActions": 1,
        "videoP25WatchedActions": 1,
        "videoP50WatchedActions": 1,
        "videoP75WatchedActions": 1,
        "videoP95WatchedActions": 1,
        "videoP100WatchedActions": 1,
        "video2SecWatchedActions": 1,
        "video6SecWatchedActions": 1,
        "video6SecFocusedViews": 1,
        "videoAvgTimeWatchedActions": 12.5,
        "costPerThruplay": 12.5,
        "funnel": {
          "landingPageViews": 1,
          "contentViews": 1,
          "searches": 1,
          "wishlistAdds": 1,
          "cartAdds": 1,
          "checkoutsInitiated": 1,
          "paymentInfoAdds": 1,
          "purchases": 1,
          "leads": 1,
          "registrationsCompleted": 1,
          "appInstalls": 1,
          "messagingConversationsStarted": 1,
          "messagingFirstReplies": 1
        },
        "engagementBreakdown": {
          "postEngagement": 1,
          "pageEngagement": 1,
          "reactions": 1,
          "comments": 1,
          "shares": 1,
          "saves": 1,
          "pageLikes": 1,
          "videoViews": 1,
          "linkClicks": 1
        },
        "lastSyncedAt": "2026-10-02T09:00:00.000Z",
        "date": "2026-10-02T09:00:00.000Z"
      }
    ],
    "breakdowns": {
      "key": [
        {}
      ]
    },
    "unsupportedBreakdowns": [
      "string"
    ],
    "breakdownHints": {
      "key": "string"
    },
    "breakdownErrors": [
      {
        "breakdown": "string",
        "message": "Hello from Pozy"
      }
    ],
    "breakdownDroppedMetrics": {
      "key": [
        "string"
      ]
    },
    "breakdownsRange": {
      "fromDate": "2026-10-01",
      "toDate": "2026-10-01"
    }
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
404	not_found	Nothing with that id exists in your workspace.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

More in Ad Insights

GETGoogle Ads search terms report GETGoogle Local Services Ads leads GETList lead conversations GETGet campaign analytics POSTGenerate keyword ideas POSTGet historical keyword metrics GETFlexible live insights query POSTSubmit async insights report GETPoll an async insights report run GETPer-creative performance inside TikTok Smart+ ads