# List campaigns

Returns campaigns, one page at a time.

```http
GET https://api.pozy.ai/v1/ads/campaigns
```

- Area: Ads / Ad Campaigns
- Auth: Authorization: Bearer pz_live_...

## Query parameters

- `includeEmpty` (boolean)
- `page` (integer)
- `limit` (integer)
- `source` (string): one of pozy, all
- `platform` (string): one of facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai, reddit
- `status` (string)
- `adAccountId` (string)
- `campaignId` (string)
- `pageId` (string)
- `accountId` (string)
- `profileId` (string)
- `fromDate` (string (date))
- `toDate` (string (date))
- `hasDelivery` (boolean)
- `minSpend` (number)
- `live` (boolean)

## Example request

```bash
curl -X GET "https://api.pozy.ai/v1/ads/campaigns?limit=20" \
  -H "Authorization: Bearer $POZY_API_KEY"
```

```ts
const res = await fetch("https://api.pozy.ai/v1/ads/campaigns?limit=20", {
  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/campaigns",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "limit": 20,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())
```

## Response 200

- `campaigns`, array of object
  - `platformCampaignId`, string
  - `platform`, string: One of `facebook`, `instagram`, `tiktok`, `linkedin`, `pinterest`, `google`, `twitter`, `openai`, `reddit`
  - `campaignName`, string
  - `status`, object
  - `reviewStatus`, string
  - `platformCampaignStatus`, string: Can be null
  - `statusReadAt`, string (date-time): Can be null
  - `nativeSettings`, object
  - `configReadAt`, string (date-time): Can be null
  - `campaignIssuesInfo`, array of object: Can be null
  - `adCount`, integer
  - `budget`, object
    - one of: Ad Campaign Budget
      - `amount`, number, required
      - `type`, string, required: One of `daily`, `lifetime`
      - `amountMicros`, string: Matches `^\d+$`
      - `explicitlyShared`, boolean: Can be null
      - `resourceName`, string: Can be null
      - `deliveryMethod`, string: Can be null
  - `campaignBudget`, object
    - one of: Ad Campaign Budget
      - `amount`, number, required
      - `type`, string, required: One of `daily`, `lifetime`
      - `amountMicros`, string: Matches `^\d+$`
      - `explicitlyShared`, boolean: Can be null
      - `resourceName`, string: Can be null
      - `deliveryMethod`, string: Can be null
  - `budgetLevel`, string: One of `campaign`, `adset`. Can be null
  - `isBudgetScheduleEnabled`, boolean: Default `false`
  - `currency`, string: Can be null
  - `metrics`, object
    - `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)
  - `platformAdAccountId`, string
  - `platformAdAccountName`, string: Can be null
  - `accountId`, string
  - `profileId`, string
  - `isSmartPlus`, boolean
  - `advertisingChannelType`, string: Can be null
  - `platformObjective`, string: Can be null
  - `optimizationGoal`, string or array of string
  - `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
  - `earliestAd`, string (date-time)
  - `latestAd`, string (date-time)
- `pagination`, object
  - `page`, integer
  - `limit`, integer
  - `total`, integer
  - `pages`, integer

```json
{
  "campaigns": [
    {
      "platformCampaignId": "68f1e8569b986839e821d8ba",
      "platform": "facebook",
      "campaignName": "Acme",
      "status": {},
      "reviewStatus": "in_review",
      "platformCampaignStatus": "instagram",
      "statusReadAt": "2026-10-02T09:00:00.000Z",
      "nativeSettings": {},
      "configReadAt": "2026-10-02T09:00:00.000Z",
      "campaignIssuesInfo": [
        {}
      ],
      "adCount": 42,
      "budget": {
        "amount": 12.5,
        "type": "daily",
        "amountMicros": "string",
        "explicitlyShared": true,
        "resourceName": "Acme",
        "deliveryMethod": "string"
      },
      "campaignBudget": {
        "amount": 12.5,
        "type": "daily",
        "amountMicros": "string",
        "explicitlyShared": true,
        "resourceName": "Acme",
        "deliveryMethod": "string"
      },
      "budgetLevel": "campaign",
      "isBudgetScheduleEnabled": false,
      "currency": "USD",
      "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"
      },
      "platformAdAccountId": "673c621a82c88059710de3fd",
      "platformAdAccountName": "instagram",
      "accountId": "696e0b682d0a31188e7a2ba9",
      "profileId": "6a0b6573846efc28aaa9a3ff",
      "isSmartPlus": true,
      "advertisingChannelType": "string",
      "platformObjective": "instagram",
      "optimizationGoal": "string",
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "bidAmount": 12.5,
      "roasAverageFloor": 12.5,
      "promotedObject": {
        "custom_event_type": "string",
        "pixel_id": "61ea7ce64c184295e2220bf7",
        "page_id": "60cae484a825fef31dae565c"
      },
      "earliestAd": "2026-10-02T09:00:00.000Z",
      "latestAd": "2026-10-02T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 42,
    "pages": 1
  }
}
```