Ads · Ad Audiences

List custom audiences

Returns custom audiences.

GEThttps://api.pozy.ai/v1/ads/audiences

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

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

Query parameters

Name	Type	Notes
`accountId`required	string
`adAccountId`required	string
`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

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

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);

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 on success

audiencesarray of object
10 child fields
- idstring
  Can be null.
- accountIdstring
- platformAudienceIdstring
- namestring
- descriptionstring
- typestring
  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.
- specobject
  One of:
  Targeting Spec (31 fields)
  userOsarray of string
  At least 1 item.
  userDevicearray of string
  At least 1 item.
  countriesarray of string
  regionsarray of string or object
  One of:
  string
  Option 2 (2 fields)
  keystringrequired
  namestring
  citiesarray of string or object
  One of:
  string
  Option 2 (4 fields)
  keystringrequired
  namestring
  radiusnumber
  distanceUnitstring
  One of mile, kilometer.
  zipsarray of object
  2 child fields
  keystringrequired
  namestring
  metrosarray of object
  2 child fields
  keystringrequired
  namestring
  countryGroupsarray 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.
  customLocationsarray of object
  6 child fields
  latitudenumberrequired
  -90 to 90.
  longitudenumberrequired
  -180 to 180.
  radiusnumberrequired
  distanceUnitstringrequired
  One of mile, kilometer.
  namestring
  addressstring
  excludedLocationsobject
  8 child fields
  countriesarray of string
  countryGroupsarray 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.
  regionsarray of object
  2 child fields
  keystringrequired
  namestring
  citiesarray of object
  3 child fields
  keystringrequired
  radiusnumber
  distanceUnitstring
  One of mile, kilometer.
  zipsarray of object
  2 child fields
  keystringrequired
  namestring
  placesarray of object
  1 child field
  keystringrequired
  neighborhoodsarray of object
  1 child field
  keystringrequired
  customLocationsarray of object
  6 child fields
  latitudenumberrequired
  -90 to 90.
  longitudenumberrequired
  -180 to 180.
  radiusnumberrequired
  distanceUnitstringrequired
  One of mile, kilometer.
  namestring
  addressstring
  ageMininteger
  13 to 100.
  ageMaxinteger
  13 to 100.
  genderstring
  One of all, male, female.
  incomeTierstring
  One of top_5, top_10, top_10_25, top_25_50.
  languagesarray of string
  interestsarray of object
  2 child fields
  idstringrequired
  namestring
  behaviorsarray of object
  2 child fields
  idstringrequired
  namestring
  workPositionsarray of object
  2 child fields
  idstringrequired
  namestring
  workEmployersarray of object
  2 child fields
  idstringrequired
  namestring
  workIndustriesarray of object
  2 child fields
  idstringrequired
  namestring
  industriesarray of string
  companySizesarray of string
  senioritiesarray of string
  jobFunctionsarray of string
  skillsarray of string
  audienceIncludearray of string
  audienceExcludearray of string
  communitiesarray of string
  excludedCommunitiesarray of string
  conversationKeywordsarray of string
  excludedConversationKeywordsarray of string
- platformstring
- sizeinteger
- statusstring

200 response

{
  "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"
    }
  ]
}

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.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

More in Ad Audiences

POSTCreate custom audience GETGet audience details PUTUpdate an audience DELDelete custom audience POSTAdd users to audience DELRemove users from audience POSTReplace audience companies