Ads

List Meta Ads custom audiences and Google Ads user lists via API

One route lists the custom audiences in the customer's ad account, with id, name, type and approximate size. The id goes in the ad set's targeting, and you read it all through the customer's connection, with no OAuth to build and no Meta app review.

The request

GET /api/ads/audiences?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

What you can do

  • List the account's custom audiences with GET /ads/audiences.
  • Use each audience's id in targeting.custom_audiences when creating an ad set.
  • See each audience's name, subtype and approximate size (approximate_size, from lower to upper).
  • Force a fresh read from the platform with refresh=true.
  • On Google Ads, list the account's open user lists (remarketing and customer match) with the same route.

Rules and limits

  • The route is read-only. Creating audiences and uploading user lists are not part of this version.
  • It is not paginated: at most 200 items come back per read.
  • Cached for 600 s per connection. meta.cached and meta.cached_at show whether it came from the cache, and refresh=true bypasses it.
  • The connection always goes in ?customer_integration= and the call needs Authorization and x-customer-token.
  • On Google Ads, Google gives a single approximate size, returned as both lower and upper.
  • On Google Ads, the results do not feed creation yet: campaigns and groups are created without location, language or audience targeting.

Main fields

FieldTypeRequiredDescription
customer_integrationstringYesThe uuid of the customer's connection. It defines the ad account. Always goes in the query.
refreshbooleanNoBypasses the 600 s cache and fetches again from the platform.
idstringNoIn the response: the audience id. It is what goes in targeting.custom_audiences.
namestringNoIn the response: the audience name in the account.
subtypestringNoIn the response: the audience type on the platform.
approximate_sizeobjectNoIn the response: the approximate size, as a range with lower and upper.

Who it is for

  • Audience picker in your SaaS

    Show the customer the audiences they already have in the account and let them choose which to use in the ad set.

  • Agency remarketing

    An agency lists the customer's visitor audiences and creates an ad set aimed at them.

  • AI agent that builds campaigns

    An agent reads the account's audiences, picks the current-customers one and uses it in the new ad set's targeting.

Works with

  • Meta Ads
  • Google Ads

Frequently asked questions

Can I create a custom audience through the API?

Not yet. The route is read-only: creating audiences and uploading user lists are not part of this version.

Where do I use the audience id?

In targeting.custom_audiences, in the ad set's targeting.

Does a new audience show up right away?

The read is cached for 600 s per connection. Use refresh=true to fetch again from the platform.

Related

See everything you can do with Ads

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.