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
| Field | Type | Required | Description |
|---|---|---|---|
| customer_integration | string | Yes | The uuid of the customer's connection. It defines the ad account. Always goes in the query. |
| refresh | boolean | No | Bypasses the 600 s cache and fetches again from the platform. |
| id | string | No | In the response: the audience id. It is what goes in targeting.custom_audiences. |
| name | string | No | In the response: the audience name in the account. |
| subtype | string | No | In the response: the audience type on the platform. |
| approximate_size | object | No | In 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.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
