The custom audiences associated with the ad account.
lookalike_audience_ids
field. See Lookalike Audiences - Managing Audiences for more information.
GET /v21.0/act_<AD_ACCOUNT_ID>/customaudiences?fields=id HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->get(
'/act_<AD_ACCOUNT_ID>/customaudiences?fields=id',
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/act_<AD_ACCOUNT_ID>/customaudiences",
{
"fields": "id"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("fields", "id");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/act_<AD_ACCOUNT_ID>/customaudiences",
params,
HttpMethod.GET,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"fields": @"id",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/customaudiences"
parameters:params
HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X GET -G \
-d 'fields="id"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences
Parameter | Description |
---|---|
business_id numeric string or integer | Optional. |
fetch_primary_audience boolean | Default value: false fetch_primary_audience |
fields list<string> | Fields to be retrieved. Default behavior is to return only the IDs. |
filtering list<Filter Object> | Filters on the report data. This parameter is an array of filter objects. |
pixel_id numeric string | Optional. |
Reading from this edge will return a JSON formatted result:
{ "
data
": [], "paging
": {} }
data
paging
Error | Description |
---|---|
100 | Invalid parameter |
80003 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience. |
190 | Invalid OAuth 2.0 Access Token |
200 | Permissions error |
2500 | Error parsing graph query |
Your ability to create custom audiences may be limited.
It is expected that you have the same audience capabilities independent of your app's status, which could be in development or live.
To create a custom audience you'll first need to create a blank audience. Then, you'll want to add people to the blank audience you just created by updating the users edge of the audience. You can create a maximum of 500 custom audiences.
customaudiences
edge from the following paths: POST /v21.0/act_<AD_ACCOUNT_ID>/customaudiences HTTP/1.1
Host: graph.facebook.com
name=My+new+Custom+Audience&subtype=CUSTOM&description=People+who+purchased+on+my+website&customer_file_source=USER_PROVIDED_ONLY
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->post(
'/act_<AD_ACCOUNT_ID>/customaudiences',
array (
'name' => 'My new Custom Audience',
'subtype' => 'CUSTOM',
'description' => 'People who purchased on my website',
'customer_file_source' => 'USER_PROVIDED_ONLY',
),
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/act_<AD_ACCOUNT_ID>/customaudiences",
"POST",
{
"name": "My new Custom Audience",
"subtype": "CUSTOM",
"description": "People who purchased on my website",
"customer_file_source": "USER_PROVIDED_ONLY"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("name", "My new Custom Audience");
params.putString("subtype", "CUSTOM");
params.putString("description", "People who purchased on my website");
params.putString("customer_file_source", "USER_PROVIDED_ONLY");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/act_<AD_ACCOUNT_ID>/customaudiences",
params,
HttpMethod.POST,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
NSDictionary *params = @{
@"name": @"My new Custom Audience",
@"subtype": @"CUSTOM",
@"description": @"People who purchased on my website",
@"customer_file_source": @"USER_PROVIDED_ONLY",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/customaudiences"
parameters:params
HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X POST \
-F 'name="My new Custom Audience"' \
-F 'subtype="CUSTOM"' \
-F 'description="People who purchased on my website"' \
-F 'customer_file_source="USER_PROVIDED_ONLY"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences
Parameter | Description |
---|---|
allowed_domains list<string> | A list of domains that the audience is restricted to. |
claim_objective enum {AUTOMOTIVE_MODEL, COLLABORATIVE_ADS, HOME_LISTING, MEDIA_TITLE, PRODUCT, TRAVEL, VEHICLE, VEHICLE_OFFER} | Specifies the objective of audiences with |
content_type enum {AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, GENERIC, HOME_LISTING, HOTEL, JOB, LOCAL_SERVICE_BUSINESS, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER} | Specifies a mandatory content type for |
customer_file_source enum {USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED} | Source of customer information in the uploaded file. |
dataset_id numeric string or integer | The offline conversion dataset associated with this audience. |
description string | The description for this custom audience |
enable_fetch_or_create boolean | If |
event_source_group numeric string or integer | Specifies event source group for |
event_sources array<JSON object> | Specifies event sources for |
facebook_page_id numeric string or integer | facebook_page_id |
is_value_based boolean | Whether the audience is used to seed a new value based lookalike audience. |
list_of_accounts list<int64> | List of user and page accounts |
lookalike_spec JSON-encoded string | The specification for creating a lookalike audience. |
name string | The name of this custom audience. |
opt_out_link string | Your opt-out URL so people can choose not to be targeted. |
origin_audience_id numeric string or integer | The ID of origin Custom Audience.The origin audience you create must have a minimum size of 100. |
pixel_id numeric string or integer | The pixel associated with this audience |
prefill boolean | You can specify |
product_set_id numeric string or integer | The Product Set to target with this audience |
retention_days int64 | Number of days to keep the user in this cluster. You can use any value between |
rule string | Audience rule to be applied on the referrer URL. Used for website custom audiences, product audiences, and video remarketing audiences. |
rule_aggregation string | Aggregation rule |
subscription_info list<enum {WHATSAPP, MESSENGER}> | subscription_info |
subtype enum {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, MESSENGER_SUBSCRIBER_LIST} | Type of custom audience, derived from original data source. |
use_for_products list<enum {ADS, MARKETING_MESSAGES}> | Default value: Vec use_for_products |
use_in_campaigns boolean | Default value: true use_in_campaigns |
id
in the return type.id
: numeric string, message
: string, Error | Description |
---|---|
200 | Permissions error |
100 | Invalid parameter |
2654 | Failed to create custom audience |
2663 | Terms of service has not been accepted. To accept, go to https://www.facebook.com/customaudiences/app/tos |
80003 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience. |
190 | Invalid OAuth 2.0 Access Token |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
2667 | Your account permissions don't allow you to create a custom audience for this event source. |