pozyDocs
Dashboard

Ads · Ad Campaigns

Get ad details

Fetches ad details.

GEThttps://api.pozy.ai/v1/ads/{adId}
Facebook and Instagram, Google Workspace, TikTok, LinkedIn, Pinterest and X and 1 moregetAd

Guides: Ads, Meta Ads, LinkedIn Ads

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

NameTypeNotes
adIdrequiredstring

Query parameters

NameTypeNotes
livebooleanDefault false
accountIdstring

Example

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

Response

200 on success

  • adobject
    36 child fields
    • _idstring
    • namestring
    • platformstring

      One of facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit.

    • profileIdstring
    • statusobject
    • configuredStatusstring

      Can be null.

    • reviewStatusobject
    • adTypestring

      One of boost, standalone.

    • creativeTypestring

      One of carousel, video, document, image. Can be null.

    • goalstring

      One of engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, page_visits, job_applicants.

    • isExternalboolean
    • syncedboolean
    • budgetobject

      Can be null.

      5 child fields
      • amountnumber
      • typestring

        One of daily, lifetime.

      • dailynumber
      • lifetimenumber
      • pacingstring
    • metricsobject

      One of:

      Ad Metrics (38 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)
    • platformAdIdstring
    • platformAdAccountIdstring
    • platformCampaignIdstring
    • platformAdSetIdstring
    • campaignNamestring
    • adSetNamestring
    • platformObjectivestring

      Can be null.

    • optimizationGoalstring

      Can be null.

    • costTypestring

      Can be null.

    • servingStatusesarray of string
    • platformAdAccountNamestring

      Can be null.

    • platformCreatedAtstring (date-time)

      Can be null.

    • bidStrategystring
    • bidAmountnumber

      Can be null.

    • roasAverageFloornumber

      Can be null.

    • promotedObjectobject

      Can be null.

      5 child fields
      • custom_event_typestring
      • pixel_idstring
      • page_idstring
      • application_idstring
      • product_set_idstring
    • creativeobject

      Can be null.

      43 child fields
      • assetGroupobject
        8 child fields
        • namestring

          1 to 128 characters.

        • finalUrlstring (URL)required

          Matches ^https?://.

        • headlinesarray of stringrequired

          At least 3 items. Up to 15 items. Each item: 1 to 30 characters.

        • longHeadlinestringrequired

          1 to 90 characters.

        • descriptionsarray of stringrequired

          At least 2 items. Up to 5 items. Each item: 1 to 90 characters.

        • businessNamestringrequired

          1 to 25 characters.

        • imagesobjectrequired
          3 child fields
          • landscapearray of string (URL)required

            At least 1 item. Up to 20 items. Each item: matches ^https?://.

          • squarearray of string (URL)required

            At least 1 item. Up to 20 items. Each item: matches ^https?://.

          • logoarray of string (URL)required

            At least 1 item. Up to 5 items. Each item: matches ^https?://.

        • youtubeVideoIdstring

          Matches ^[A-Za-z0-9_-]{11}$.

      • assetGroupResourceNamestring
      • headlinesarray of string or object

        Up to 15 items.

        One of:

        string
        Google Rsa Headline (2 fields)
        • textstringrequired

          1 to 30 characters.

        • pinnedFieldstring

          One of HEADLINE_1, HEADLINE_2, HEADLINE_3.

      • descriptionsarray of string or object

        Up to 4 items.

        One of:

        string
        Google Rsa Description (2 fields)
        • textstringrequired

          1 to 90 characters.

        • pinnedFieldstring

          One of DESCRIPTION_1, DESCRIPTION_2.

      • headlinestring
      • bodiesarray of string
      • descriptionstring
      • callToActionstring
      • leadGenFormIdstring
      • imageHashstring
      • urlTagsstring

        Can be null.

      • finalUrlsarray of string (URL)

        At least 1 item.

      • thumbnailUrlstring

        Can be null.

      • imageUrlstring
      • assetResourceNamestring
      • assetsobject
        2 child fields
        • marketingImagesarray of object
          1 child field
          • resourceNamestring
        • squareMarketingImagesarray of object
          1 child field
          • resourceNamestring
      • videoIdstring

        Can be null.

      • videoUrlstring

        Can be null.

      • creativeIdstring

        Can be null.

      • creativeFeaturesmap of string
      • catalogobject
        3 child fields
        • productSetIdstring
        • formatstring

          One of single_image, carousel_images_multi_items, carousel_images_single_item, carousel_slideshows.

        • formatTransformationSpecarray of object
          2 child fields
          • formatstring
          • data_sourcearray of string
      • objectTypestring
      • objectStoryIdstring

        Can be null.

      • effectiveObjectStoryIdstring

        Can be null.

      • pageIdstring

        Can be null.

      • effectiveInstagramMediaIdstring

        Can be null.

      • instagramUserIdstring

        Can be null.

      • instagramPermalinkUrlstring

        Can be null.

      • mediaUrlsarray of string
      • carouselCardsarray of object
        7 child fields
        • imageUrlstring
        • imageHashstring
        • headlinestring
        • descriptionstring
        • linkUrlstring
        • callToActionstring
        • videoIdstring
      • isServingboolean

        Can be null.

      • adFormatstring

        Can be null.

      • servingHoldReasonsarray of string
      • bodystring
      • googleHeadlinestring
      • googleDescriptionstring
      • youtubeVideoIdsarray of string
      • linkUrlstring
      • whatsappPhoneNumberstring
      • instagramVideoFallbackobject
        4 child fields
        • kindstringrequired

          One of instagram_video_reuploaded, instagram_video_rehosted_copy.

        • linkedToOriginalPostbooleanrequired
        • videoIdstringrequired
        • platformErrorobjectrequired
          4 child fields
          • codeinteger
          • subcodeinteger
          • messagestringrequired
          • fbtraceIdstring
      • pinterestImageUrlstring
      • pinterestTitlestring
      • pinterestDescriptionstring
    • targetingobject
    • scheduleobject

      Can be null.

      2 child fields
      • startDatestring (date-time)
      • endDatestring (date-time)
    • rejectionReasonstring
    • createdAtstring (date-time)
    • updatedAtstring (date-time)
  • cachedAtstring (date-time)

    Can be null.

  • staleboolean
  • statusReadAtstring (date-time)

    Can be null.

  • darkPostobject
    10 child fields
    • platformstring

      One of facebook.

    • platformPostIdstring
    • pageIdstring
    • isDarkPostboolean
    • adIdstring

      Can be null.

    • accountIdstring

      Can be null.

    • facebookAccountIdstring
    • platformAdAccountIdsarray of string
    • firstSeenAtstring (date-time)
    • lastActivityAtstring (date-time)
200 response
{
  "ad": {
    "_id": "635d87e261ae344ef27fd1df",
    "name": "Acme",
    "platform": "facebook",
    "profileId": "6a0b6573846efc28aaa9a3ff",
    "status": {},
    "configuredStatus": "active",
    "reviewStatus": {},
    "adType": "boost",
    "creativeType": "carousel",
    "goal": "engagement",
    "isExternal": true,
    "synced": true,
    "budget": {
      "amount": 12.5,
      "type": "daily",
      "daily": 12.5,
      "lifetime": 12.5,
      "pacing": "string"
    },
    "metrics": {
      "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"
    },
    "platformAdId": "64149c3e561c1c5ac800f87a",
    "platformAdAccountId": "673c621a82c88059710de3fd",
    "platformCampaignId": "68f1e8569b986839e821d8ba",
    "platformAdSetId": "6749c05fd96acf71ce38cbc7",
    "campaignName": "Acme",
    "adSetName": "Acme",
    "platformObjective": "instagram",
    "optimizationGoal": "string",
    "costType": "string",
    "servingStatuses": [
      "active"
    ],
    "platformAdAccountName": "instagram",
    "platformCreatedAt": "2026-10-02T09:00:00.000Z",
    "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
    "bidAmount": 12.5,
    "roasAverageFloor": 12.5,
    "promotedObject": {
      "custom_event_type": "string",
      "pixel_id": "61ea7ce64c184295e2220bf7",
      "page_id": "60cae484a825fef31dae565c",
      "application_id": "6a49643c60aa0c1725a69ce7",
      "product_set_id": "6a424f3abe2064286a5e3a4b"
    },
    "creative": {
      "assetGroup": {
        "name": "Acme",
        "finalUrl": "https://pozy.ai/media/example-1.jpg",
        "headlines": [
          "string"
        ],
        "longHeadline": "string",
        "descriptions": [
          "string"
        ],
        "businessName": "Acme",
        "images": {
          "landscape": [
            "https://pozy.ai/media/example-1.jpg"
          ],
          "square": [
            "https://pozy.ai/media/example-1.jpg"
          ],
          "logo": [
            "https://pozy.ai/media/example-1.jpg"
          ]
        },
        "youtubeVideoId": "65303c153dd819143b179354"
      },
      "assetGroupResourceName": "Acme",
      "headlines": [
        "string"
      ],
      "descriptions": [
        "string"
      ],
      "headline": "Launch day",
      "bodies": [
        "string"
      ],
      "description": "A short description",
      "callToAction": "string",
      "leadGenFormId": "66d3effa66e41a45e5deee45",
      "imageHash": "string",
      "urlTags": "https://pozy.ai/media/example-1.jpg",
      "finalUrls": [
        "https://pozy.ai/media/example-1.jpg"
      ],
      "thumbnailUrl": "https://pozy.ai/media/example-1.jpg",
      "imageUrl": "https://pozy.ai/media/example-1.jpg",
      "assetResourceName": "Acme",
      "assets": {
        "marketingImages": [
          {
            "resourceName": "Acme"
          }
        ],
        "squareMarketingImages": [
          {
            "resourceName": "Acme"
          }
        ]
      },
      "videoId": "65fd297a0da74ab358dd11e9",
      "videoUrl": "https://pozy.ai/media/example-1.jpg",
      "creativeId": "68c59681516c848d73eebe49",
      "creativeFeatures": {
        "key": "OPT_IN"
      },
      "catalog": {
        "productSetId": "6cdea2a8973aaa3d924aa2e8",
        "format": "single_image",
        "formatTransformationSpec": [
          {
            "format": "string",
            "data_source": [
              "string"
            ]
          }
        ]
      },
      "objectType": "string",
      "objectStoryId": "64c3ae81d059271ce0c220b5",
      "effectiveObjectStoryId": "67c37b0ffda71894bd7eea2c",
      "pageId": "675e1e95e076854531b4d051",
      "effectiveInstagramMediaId": "612675e5315fb71660656b0b",
      "instagramUserId": "665a608ca13236ff56e25aae",
      "instagramPermalinkUrl": "https://pozy.ai/media/example-1.jpg",
      "mediaUrls": [
        "https://pozy.ai/media/example-1.jpg"
      ],
      "carouselCards": [
        {
          "imageUrl": "https://pozy.ai/media/example-1.jpg",
          "imageHash": "string",
          "headline": "Launch day",
          "description": "A short description",
          "linkUrl": "https://pozy.ai/media/example-1.jpg",
          "callToAction": "string",
          "videoId": "65fd297a0da74ab358dd11e9"
        }
      ],
      "isServing": true,
      "adFormat": "string",
      "servingHoldReasons": [
        "string"
      ],
      "body": "string",
      "googleHeadline": "string",
      "googleDescription": "string",
      "youtubeVideoIds": [
        "string"
      ],
      "linkUrl": "https://pozy.ai/media/example-1.jpg",
      "whatsappPhoneNumber": "+14155550123",
      "instagramVideoFallback": {
        "kind": "instagram_video_reuploaded",
        "linkedToOriginalPost": true,
        "videoId": "65fd297a0da74ab358dd11e9",
        "platformError": {
          "code": 1,
          "subcode": 1,
          "message": "Hello from Pozy",
          "fbtraceId": "683a6bd99e02a3ca186c487f"
        }
      },
      "pinterestImageUrl": "https://pozy.ai/media/example-1.jpg",
      "pinterestTitle": "string",
      "pinterestDescription": "string"
    },
    "targeting": {},
    "schedule": {
      "startDate": "2026-10-02T09:00:00.000Z",
      "endDate": "2026-10-02T09:00:00.000Z"
    },
    "rejectionReason": "string",
    "createdAt": "2026-10-02T09:00:00.000Z",
    "updatedAt": "2026-10-02T09:00:00.000Z"
  },
  "cachedAt": "2026-10-02T09:00:00.000Z",
  "stale": true,
  "statusReadAt": "2026-10-02T09:00:00.000Z",
  "darkPost": {
    "platform": "facebook",
    "platformPostId": "637f799b3039e6602e83fa4f",
    "pageId": "675e1e95e076854531b4d051",
    "isDarkPost": true,
    "adId": "6f40fa2fb0a7e728dd1a73b7",
    "accountId": "696e0b682d0a31188e7a2ba9",
    "facebookAccountId": "6f0d7b312e6dab1ad6b6ee17",
    "platformAdAccountIds": [
      "instagram"
    ],
    "firstSeenAt": "2026-10-02T09:00:00.000Z",
    "lastActivityAt": "2026-10-02T09:00:00.000Z"
  }
}

Errors

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

400invalid_request_errorA parameter or body field is missing or invalid. param names it.
401authentication_errorThe API key is missing, revoked or expired.
403permission_errorThe key is scoped to other profiles or has this resource group disabled.
404not_foundNothing with that id exists in your workspace.
429rate_limit_errorToo many requests this minute. Wait for Retry-After seconds.

Every code is listed in Errors.

More in Ad Campaigns

GETList adsGETList Google Ads recommendationsPOSTApply Google Ads recommendationsPOSTDismiss Google Ads recommendationsGETList portfolio bid strategiesPOSTCreate portfolio bid strategyPATCHUpdate portfolio bid strategyGETList shared budgetsPOSTCreate a shared budgetGETList Search keywordsPOSTAdd Search ad-group keywordsPATCHPause or enable a Search keywordDELRemove a Search keywordGETList campaignsPOSTCreate a standalone campaignPUTPause or resume a campaignGETRead a campaign's ad schedule (dayparting)PUTReplace a campaign's ad schedule (dayparting)GETRead a campaign's current biddingGETGet live campaign detailsPUTUpdate a campaignDELDelete a campaignGETList campaign-level negative keywordsPUTReplace campaign-level negative keywordsPOSTPause or resume many campaignsPOSTDuplicate a campaignGETRead a Google campaign's device, location, excluded location, and language targetingPUTEdit a Google campaign's device, location, excluded location, or language targetingGETList ad setsPOSTCreate a standalone ad groupPOSTDuplicate an ad setPOSTDuplicate an adGETGet live ad-set detailsPUTUpdate an ad setDELDelete an ad setGETRead a Reddit ad group's targeting and schedulePUTPause or resume a single ad setGETGet campaign treeGETGet daily account metricsPUTUpdate adDELCancel an adPUTPause or resume a single adGETList campaign assetsPOSTAttach campaign assetsPUTUpdate campaign assetsDELRemove campaign assetsGETList ad-group assetsPOSTAttach ad-group assetsPUTUpdate ad-group assetsDELRemove ad-group assetsGETRead the platform's review verdict for an adGETReview status of each creative in a TikTok Smart+ adGETList ads that need attentionPOSTDismiss an ads alertGETReview status of every TikTok Smart+ ad of an advertiserGETList campaign negative listsPUTReplace campaign negative listsPOSTBoost post as adGETList Performance Max asset groupsPOSTCreate a Performance Max asset groupGETGet a Performance Max asset groupPATCHUpdate a Performance Max asset groupDELRemove a Performance Max asset groupPOSTLink or unlink asset group assetsPUTReplace an asset group's listing-group treePOSTCreate standalone adGETGet campaign conversion goalsPATCHUpdate campaign conversion goals