CustomAudiences

Query information about custom audiences defined for your ad accounts.

Table Specific Information

Custom audiences in Facebook Ads represent an advertiser-defined audience to deliver ads to.

SELECT

The ExternalEventSource column is not returned by default, as it requires additional permissions for the underlying AdPixels object. To retrieve information for this column, it should be set in the query projection explicitly:

SELECT Id, Name, ExternalEventSource FROM CustomAudiences

Note: Listing CustomAudiences while selecting ExternalEventSource will only return CustomAudiences where the currently authenticated app has access to the underlying AdsPixel object.

Insert

When inserting CustomAudiences, at least a Name, Subtype, and CustomerFileSource must be specified:

INSERT INTO CustomAudiences (Name, Subtype, CustomerFileSource) VALUES ('Custom Audience', 'CUSTOM', 'USER_PROVIDED_ONLY')

Note: To insert users to a Custom Audience, the AddCustomAudienceUsers stored procedure must be used.

Delete

When deleting CustomAudiences, the Id of the object should be specified.

DELETE FROM CustomAudiences WHERE Id='123456'

Note: To delete users from a Custom Audience, the DeleteCustomAudienceUsers stored procedure must be used.

Columns


Name	Type	ReadOnly	Description
ID [KEY]	String	True	The ID of the custom audience.
Account_ID	String	True	The ID of the custom audience's ad account.
Name	String	False	The name of the custom audience.
Description	String	False	The description of the custom audience.
Subtype	String	False	The subtype of the custom audience. Valid values are: CUSTOM, PRIMARY, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, MANAGED, PARTNER, VIDEO, LOOKALIKE, ENGAGEMENT, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX, MEASUREMENT, REGULATED_CATEGORIES_AUDIENCE, BIDDING, SUBSCRIBER_SEGMENT, EXCLUSION
TimeCreated	Datetime	True	Creation time of the custom audience.
TimeUpdated	Datetime	True	Last updated time of the custom audience.
TimeContentUpdated	Datetime	True	Last update of people in this custom audience. Only supported for Customer List Custom Audiences.
Rule	String	False	Audience rules to be applied on the referrer URL.
RuleAggregation	String	False	Aggregation on top of the audience rule.
ApproximateCountLowerBound	Integer	True	Lower bound of the approximate number of people in this audience.
ApproximateCountUpperBound	Integer	True	Upper bound of the approximate number of people in this audience.
PixelID	String	False	ID of pixel which is collecting events for Website Custom audience.
RetentionDays	Integer	False	Number of days to retain user in this audience. Can be any value between 1 and 180 days. Defaults to forever if left unspecified. Only available for Customer File Custom Audience.
CustomerFileSource	String	False	Source of customer information in the uploaded file.
DataSource	String	True	JSON dictionary to indicate the method by which the custom audience was created.
DeliveryStatus	String	True	JSON dictionary which indicates whether an audience can be used in ads.
ExternalEventSource	String	True	JSON dictionary containing the pixel id whose traffic generated the custom audience.
OperationStatus	String	True	JSON dictionary containing status code and description of last operation.
PermissionForActions	String	True	JSON dictionary of permissions (string) to boolean value if the custom audience has that permission.
IsValueBased	Boolean	False	Whether the audience is used to seed value based lookalike.
OptOutLink	String	False	Opt-out URL for audience members who choose not to be targeted.

Pseudo-Columns

Pseudo column fields are used in the WHERE clause of SELECT statements and offer a more granular control over the tuples that are returned from the data source. For more information, see the WHERE clause section.


Name	Type	Description
EnableFetchOrCreate	Boolean	When set to true during INSERT, this parameter causes any identical custom audience to be fetched. Prevents INSERT of duplicate audience.
UseInCampaigns	Boolean	Controls whether this custom audience will be used in campaigns. Defaults to true.
Prefill	Boolean	If true, website traffic recorded prior to audience creation will be used to initialize this audience. If false, only website traffic garnered after the creation of this audience will be used.
DatasetId	Integer	ID of offline conversion dataset associated with this audience.
ContentType	String	Specifies content type for TRAVEL claim objective. Mandatory if creating audience with TRAVEL claim objective. Valid values are: AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, GENERIC, HOME_LISTING, HOTEL, JOB, LOCAL_SERVICE_BUSINESS, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER
ClaimObjective	String	Specifies objective of audiences with CLAIM subtype. Valid values are: AUTOMOTIVE_MODEL, COLLABORATIVE_ADS, HOME_LISTING, MEDIA_TITLE, PRODUCT, TRAVEL, VEHICLE, VEHICLE_OFFER.
EventSourceGroup	Integer	Specifies event source group if using TRAVEL claim objective.
ProductSetId	Integer	Id of the Product Set to target with this audience.
OriginAudienceId	Integer	Id of origin Custom Audience. Origin audience must have a minimum size of 100.