# List ads Returns ads, one page at a time. ```http GET https://api.pozy.ai/v1/ads ``` - Area: Ads / Ad Campaigns - Auth: Authorization: Bearer pz_live_... ## Query parameters - `page` (integer) - `limit` (integer) - `source` (string): one of pozy, all - `status` (string) - `platform` (string): one of facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit - `accountId` (string) - `adAccountId` (string) - `pageId` (string) - `profileId` (string) - `campaignId` (string) - `adSetId` (string) - `platformAdId` (string) - `effectiveObjectStoryId` (string) - `effectiveInstagramMediaId` (string) - `fromDate` (string (date)) - `toDate` (string (date)) ## Example request ```bash curl -X GET "https://api.pozy.ai/v1/ads?limit=50" \ -H "Authorization: Bearer $POZY_API_KEY" ``` ```ts const res = await fetch("https://api.pozy.ai/v1/ads?limit=50", { 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); ``` ```python import os import requests resp = requests.get( "https://api.pozy.ai/v1/ads", headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"}, params={ "limit": 50, }, timeout=30, ) resp.raise_for_status() print(resp.json()) ``` ## Response 200 - `ads`, array of object - `_id`, string - `name`, string - `platform`, string: One of `facebook`, `instagram`, `tiktok`, `linkedin`, `pinterest`, `google`, `twitter`, `openai`, `reddit` - `profileId`, string - `status`, object - `configuredStatus`, string: Can be null - `reviewStatus`, object - `adType`, string: One of `boost`, `standalone` - `creativeType`, string: One of `carousel`, `video`, `document`, `image`. Can be null - `goal`, string: One of `engagement`, `traffic`, `awareness`, `video_views`, `lead_generation`, `lead_conversion`, `conversions`, `app_promotion`, `catalog_sales`, `page_likes`, `page_visits`, `job_applicants` - `isExternal`, boolean - `synced`, boolean - `budget`, object: Can be null - `amount`, number - `type`, string: One of `daily`, `lifetime` - `daily`, number - `lifetime`, number - `pacing`, string - `metrics`, object - one of: Ad Metrics - `spend`, number - `impressions`, integer - `reach`, integer - `clicks`, integer - `ctr`, number - `cpc`, number - `cpm`, number - `engagement`, integer - `conversions`, number - `allConversions`, number - `costPerConversion`, number - `actions`, map of integer - `actionValues`, map of number - `purchaseValue`, number - `roas`, number - `costPerAction`, map of number - `outboundClicks`, integer - `outboundClicksCtr`, number - `inlineLinkClicks`, integer - `inlineLinkClickCtr`, number - `uniqueClicks`, integer - `uniqueCtr`, number - `videoPlayActions`, integer - `video30SecWatchedActions`, integer - `videoThruplayWatchedActions`, integer - `videoP25WatchedActions`, integer - `videoP50WatchedActions`, integer - `videoP75WatchedActions`, integer - `videoP95WatchedActions`, integer - `videoP100WatchedActions`, integer - `video2SecWatchedActions`, integer - `video6SecWatchedActions`, integer - `video6SecFocusedViews`, integer - `videoAvgTimeWatchedActions`, number - `costPerThruplay`, number - `funnel`, object - `landingPageViews`, integer - `contentViews`, integer - `searches`, integer - `wishlistAdds`, integer - `cartAdds`, integer - `checkoutsInitiated`, integer - `paymentInfoAdds`, integer - `purchases`, integer - `leads`, integer - `registrationsCompleted`, integer - `appInstalls`, integer - `messagingConversationsStarted`, integer - `messagingFirstReplies`, integer - `engagementBreakdown`, object - `postEngagement`, integer - `pageEngagement`, integer - `reactions`, integer - `comments`, integer - `shares`, integer - `saves`, integer - `pageLikes`, integer - `videoViews`, integer - `linkClicks`, integer - `lastSyncedAt`, string (date-time) - `platformAdId`, string - `platformAdAccountId`, string - `platformCampaignId`, string - `platformAdSetId`, string - `campaignName`, string - `adSetName`, string - `platformObjective`, string: Can be null - `optimizationGoal`, string: Can be null - `costType`, string: Can be null - `servingStatuses`, array of string - `platformAdAccountName`, string: Can be null - `platformCreatedAt`, string (date-time): Can be null - `bidStrategy`, string - `bidAmount`, number: Can be null - `roasAverageFloor`, number: Can be null - `promotedObject`, object: Can be null - `custom_event_type`, string - `pixel_id`, string - `page_id`, string - `application_id`, string - `product_set_id`, string - `creative`, object: Can be null - `assetGroup`, object - `name`, string: 1 to 128 characters - `finalUrl`, string (URL), required: Matches `^https?://` - `headlines`, array of string, required: At least 3 items. Up to 15 items. Each item: 1 to 30 characters - `longHeadline`, string, required: 1 to 90 characters - `descriptions`, array of string, required: At least 2 items. Up to 5 items. Each item: 1 to 90 characters - `businessName`, string, required: 1 to 25 characters - `images`, object, required - `landscape`, array of string (URL), required: At least 1 item. Up to 20 items. Each item: matches `^https?://` - `square`, array of string (URL), required: At least 1 item. Up to 20 items. Each item: matches `^https?://` - `logo`, array of string (URL), required: At least 1 item. Up to 5 items. Each item: matches `^https?://` - `youtubeVideoId`, string: Matches `^[A-Za-z0-9_-]{11}$` - `assetGroupResourceName`, string - `headlines`, array of string or object: Up to 15 items - one of: string - one of: Google Rsa Headline - `text`, string, required: 1 to 30 characters - `pinnedField`, string: One of `HEADLINE_1`, `HEADLINE_2`, `HEADLINE_3` - `descriptions`, array of string or object: Up to 4 items - one of: string - one of: Google Rsa Description - `text`, string, required: 1 to 90 characters - `pinnedField`, string: One of `DESCRIPTION_1`, `DESCRIPTION_2` - `headline`, string - `bodies`, array of string - `description`, string - `callToAction`, string - `leadGenFormId`, string - `imageHash`, string - `urlTags`, string: Can be null - `finalUrls`, array of string (URL): At least 1 item - `thumbnailUrl`, string: Can be null - `imageUrl`, string - `assetResourceName`, string - `assets`, object - `marketingImages`, array of object - `resourceName`, string - `squareMarketingImages`, array of object - `resourceName`, string - `videoId`, string: Can be null - `videoUrl`, string: Can be null - `creativeId`, string: Can be null - `creativeFeatures`, map of string - `catalog`, object - `productSetId`, string - `format`, string: One of `single_image`, `carousel_images_multi_items`, `carousel_images_single_item`, `carousel_slideshows` - `formatTransformationSpec`, array of object - `format`, string - `data_source`, array of string - `objectType`, string - `objectStoryId`, string: Can be null - `effectiveObjectStoryId`, string: Can be null - `pageId`, string: Can be null - `effectiveInstagramMediaId`, string: Can be null - `instagramUserId`, string: Can be null - `instagramPermalinkUrl`, string: Can be null - `mediaUrls`, array of string - `carouselCards`, array of object - `imageUrl`, string - `imageHash`, string - `headline`, string - `description`, string - `linkUrl`, string - `callToAction`, string - `videoId`, string - `isServing`, boolean: Can be null - `adFormat`, string: Can be null - `servingHoldReasons`, array of string - `body`, string - `googleHeadline`, string - `googleDescription`, string - `youtubeVideoIds`, array of string - `linkUrl`, string - `whatsappPhoneNumber`, string - `instagramVideoFallback`, object - `kind`, string, required: One of `instagram_video_reuploaded`, `instagram_video_rehosted_copy` - `linkedToOriginalPost`, boolean, required - `videoId`, string, required - `platformError`, object, required - `code`, integer - `subcode`, integer - `message`, string, required - `fbtraceId`, string - `pinterestImageUrl`, string - `pinterestTitle`, string - `pinterestDescription`, string - `targeting`, object - `schedule`, object: Can be null - `startDate`, string (date-time) - `endDate`, string (date-time) - `rejectionReason`, string - `createdAt`, string (date-time) - `updatedAt`, string (date-time) - `pagination`, object - `page`, integer - `limit`, integer - `total`, integer - `pages`, integer - `backfillPending`, boolean ```json { "ads": [ { "_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" } ], "pagination": { "page": 1, "limit": 1, "total": 42, "pages": 1 }, "backfillPending": true } ```