The custom audiences associated with the ad account.
lookalike_audience_ids
field. See Lookalike Audiences - Managing Audiences
for more information. GET /v20.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/v20.0/act_<AD_ACCOUNT_ID>/customaudiences
Parameter | Description |
---|---|
business_id
numeric string or integer
|
Optional.This param assists with filters, such as recently used. |
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. |
field
string
|
Required
|
operator
enum {EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ENDS_WITH, ANY, ALL, AFTER, BEFORE, ON_OR_AFTER, ON_OR_BEFORE, NONE, TOP}
|
Required
|
value
string
|
Required
|
pixel_id
numeric string
|
Optional.This param fetches audiences associated to specific pixel. |
Reading from this edge will return a JSON formatted result:
{ "
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 /v20.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/v20.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 |
id
int64
|
id Required
|
type
enum {APP, OFFLINE_EVENTS, PAGE, PIXEL}
|
type Required
|
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 |
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}
|
Type of custom audience, derived from original data source. |
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 |
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. |
2663 | Terms of service has not been accepted. To accept, go to https://www.facebook.com/customaudiences/app/tos |
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. |