# List custom audiences

Returns custom audiences.

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

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

## Query parameters

- `accountId` (string, required)
- `adAccountId` (string, required)
- `platform` (string): one of facebook, instagram, googleads, tiktok, tiktokads, pinterest, linkedin, linkedinads, twitter, xads, redditads
- `type` (string): one of customer_list, company_list, engagement, meta_engagement, website, website_retargeting, lookalike, saved_targeting

## Example request

```bash
curl -X GET "https://api.pozy.ai/v1/ads/audiences?accountId=696e0b682d0a31188e7a2ba9&adAccountId=666219aad7bab67ace411e4f" \
  -H "Authorization: Bearer $POZY_API_KEY"
```

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

## Response 200

- `audiences`, array of object
  - `id`, string: Can be null
  - `accountId`, string
  - `platformAudienceId`, string
  - `name`, string
  - `description`, string
  - `type`, string: One of `customer_list`, `company_list`, `engagement`, `meta_engagement`, `tiktok_engagement`, `pinterest_engagement`, `website`, `website_retargeting`, `lookalike`, `saved_targeting`, `reddit_engagement`, `third_party`, `in_market`
  - `spec`, object
    - one of: Targeting Spec
      - `userOs`, array of string: At least 1 item
      - `userDevice`, array of string: At least 1 item
      - `countries`, array of string
      - `regions`, array of string or object
        - one of: string
        - one of: Option 2
          - `key`, string, required
          - `name`, string
      - `cities`, array of string or object
        - one of: string
        - one of: Option 2
          - `key`, string, required
          - `name`, string
          - `radius`, number
          - `distanceUnit`, string: One of `mile`, `kilometer`
      - `zips`, array of object
        - `key`, string, required
        - `name`, string
      - `metros`, array of object
        - `key`, string, required
        - `name`, string
      - `countryGroups`, array of string: Each item: one of `africa`, `asia`, `europe`, `north_america`, `south_america`, `oceania`, `central_america`, `caribbean`, `eea`, `euro_area`, `nafta`, `mercosur`, `afta`, `apec`, `gcc`, `cisfta`, `emerging_markets`, `itunes_app_store`, `android_free_store`, `android_paid_store`
      - `customLocations`, array of object
        - `latitude`, number, required: -90 to 90
        - `longitude`, number, required: -180 to 180
        - `radius`, number, required
        - `distanceUnit`, string, required: One of `mile`, `kilometer`
        - `name`, string
        - `address`, string
      - `excludedLocations`, object
        - `countries`, array of string
        - `countryGroups`, array of string: Each item: one of `africa`, `asia`, `europe`, `north_america`, `south_america`, `oceania`, `central_america`, `caribbean`, `eea`, `euro_area`, `nafta`, `mercosur`, `afta`, `apec`, `gcc`, `cisfta`, `emerging_markets`, `itunes_app_store`, `android_free_store`, `android_paid_store`
        - `regions`, array of object
          - `key`, string, required
          - `name`, string
        - `cities`, array of object
          - `key`, string, required
          - `radius`, number
          - `distanceUnit`, string: One of `mile`, `kilometer`
        - `zips`, array of object
          - `key`, string, required
          - `name`, string
        - `places`, array of object
          - `key`, string, required
        - `neighborhoods`, array of object
          - `key`, string, required
        - `customLocations`, array of object
          - `latitude`, number, required: -90 to 90
          - `longitude`, number, required: -180 to 180
          - `radius`, number, required
          - `distanceUnit`, string, required: One of `mile`, `kilometer`
          - `name`, string
          - `address`, string
      - `ageMin`, integer: 13 to 100
      - `ageMax`, integer: 13 to 100
      - `gender`, string: One of `all`, `male`, `female`
      - `incomeTier`, string: One of `top_5`, `top_10`, `top_10_25`, `top_25_50`
      - `languages`, array of string
      - `interests`, array of object
        - `id`, string, required
        - `name`, string
      - `behaviors`, array of object
        - `id`, string, required
        - `name`, string
      - `workPositions`, array of object
        - `id`, string, required
        - `name`, string
      - `workEmployers`, array of object
        - `id`, string, required
        - `name`, string
      - `workIndustries`, array of object
        - `id`, string, required
        - `name`, string
      - `industries`, array of string
      - `companySizes`, array of string
      - `seniorities`, array of string
      - `jobFunctions`, array of string
      - `skills`, array of string
      - `audienceInclude`, array of string
      - `audienceExclude`, array of string
      - `communities`, array of string
      - `excludedCommunities`, array of string
      - `conversationKeywords`, array of string
      - `excludedConversationKeywords`, array of string
  - `platform`, string
  - `size`, integer
  - `status`, string

```json
{
  "audiences": [
    {
      "id": "6bfebd43ddc270f6d2c56fc5",
      "accountId": "696e0b682d0a31188e7a2ba9",
      "platformAudienceId": "6c0d752332e3484872dc8c12",
      "name": "Acme",
      "description": "A short description",
      "type": "customer_list",
      "spec": {
        "userOs": [
          "string"
        ],
        "userDevice": [
          "string"
        ],
        "countries": [
          "string"
        ],
        "regions": [
          "string"
        ],
        "cities": [
          "string"
        ],
        "zips": [
          {
            "key": "string",
            "name": "Acme"
          }
        ],
        "metros": [
          {
            "key": "string",
            "name": "Acme"
          }
        ],
        "countryGroups": [
          "africa"
        ],
        "customLocations": [
          {
            "latitude": 12.5,
            "longitude": 12.5,
            "radius": 12.5,
            "distanceUnit": "mile",
            "name": "Acme",
            "address": "string"
          }
        ],
        "excludedLocations": {
          "countries": [
            "string"
          ],
          "countryGroups": [
            "africa"
          ],
          "regions": [
            {
              "key": "string",
              "name": "Acme"
            }
          ],
          "cities": [
            {
              "key": "string",
              "radius": 12.5,
              "distanceUnit": "mile"
            }
          ],
          "zips": [
            {
              "key": "string",
              "name": "Acme"
            }
          ],
          "places": [
            {
              "key": "string"
            }
          ],
          "neighborhoods": [
            {
              "key": "string"
            }
          ],
          "customLocations": [
            {
              "latitude": 12.5,
              "longitude": 12.5,
              "radius": 12.5,
              "distanceUnit": "mile",
              "name": "Acme",
              "address": "string"
            }
          ]
        },
        "ageMin": 13,
        "ageMax": 13,
        "gender": "all",
        "incomeTier": "top_5",
        "languages": [
          "string"
        ],
        "interests": [
          {
            "id": "6bfebd43ddc270f6d2c56fc5",
            "name": "Acme"
          }
        ],
        "behaviors": [
          {
            "id": "6bfebd43ddc270f6d2c56fc5",
            "name": "Acme"
          }
        ],
        "workPositions": [
          {
            "id": "6bfebd43ddc270f6d2c56fc5",
            "name": "Acme"
          }
        ],
        "workEmployers": [
          {
            "id": "6bfebd43ddc270f6d2c56fc5",
            "name": "Acme"
          }
        ],
        "workIndustries": [
          {
            "id": "6bfebd43ddc270f6d2c56fc5",
            "name": "Acme"
          }
        ],
        "industries": [
          "string"
        ],
        "companySizes": [
          "string"
        ],
        "seniorities": [
          "string"
        ],
        "jobFunctions": [
          "string"
        ],
        "skills": [
          "string"
        ],
        "audienceInclude": [
          "string"
        ],
        "audienceExclude": [
          "string"
        ],
        "communities": [
          "string"
        ],
        "excludedCommunities": [
          "string"
        ],
        "conversationKeywords": [
          "string"
        ],
        "excludedConversationKeywords": [
          "string"
        ]
      },
      "platform": "instagram",
      "size": 482133,
      "status": "active"
    }
  ]
}
```