Marketing API Version

Ad Account Customaudiences

Reading

The custom audiences owned by/shared with this ad account

Graph API Explorer
GET /v2.10/{ad-account-id}/customaudiences HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{ad-account-id}/customaudiences'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{ad-account-id}/customaudiences",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-account-id}/customaudiences",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{ad-account-id}/customaudiences"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
business_id
numeric string or integer

optional param assist with filters such as recently used

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, ANY, ALL, AFTER, BEFORE, NONE}
Required
value
string
Required
pixel_id
numeric string or integer

optional param to fetch audience only assoicated to specific pixel

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of CustomAudience nodes.

paging

For more details about pagination, see the Graph API guide.

Validation Rules

ErrorDescription
100Invalid parameter
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
200Permissions error
273This Ads API call requires the user to be admin of the ad account
272This Ads API call requires the user to be admin of the application
278Reading advertisements requires an access token with the extended permission ads_read

Creating

You can create a maximum of 500 custom audiences.

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 make a POST request to customaudiences edge from the following paths:
When posting to this edge, a CustomAudience will be created.

Parameters

NameDescription
allowed_domains
list<string>

A list of domains that the audience is restricted to

claim_objective
enum {AUTO_OFFER, HOME_LISTING, PRODUCT, TRAVEL, VEHICLE}

Specifies the objective of audiences with subtype = CLAIM

content_type
enum {AUTO_OFFER, DESTINATION, FLIGHT, HOME_LISTING, HOTEL, VEHICLE}

Specifies a mandatory content type for claim_objective = TRAVEL

dataset_id
numeric string or integer

The offline conversion dataset associated with this audience

description
string

The description for this custom audience

event_source_group
numeric string or integer

Specifies event source group for claim_objective = TRAVEL

is_value_based
boolean

Whether the audience is used to seed value based lookalike

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

true: Include website traffic recorded prior to the audience creation.
false: Only include website traffic beginning at the time of the audience creation.

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 1 and 365 days. Defaults to forever if not specified

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, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, PARTNER, MANAGED, VIDEO, LOOKALIKE, ENGAGEMENT, DATA_SET, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX}

Type of custom audience, derived from original data source.
Note: COMBINATION subtype is only used by Power Editor and Ads Manager, and not available through the API.
Audience size limit for selected subtype:
CUSTOM: 500
WEBSITE: 200
APP: 200
LOOKALIKE: 10000
CLAIM: 500

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
2654Failed to create custom audience
2663Terms of service has not been accepted. To accept, go to https://www.facebook.com/customaudiences/app/tos
200Permissions error
100Invalid parameter
2655Terms of service has not been accepted. To accept, go to https://www.facebook.com/ads/manage/customaudiences/tos.php
2664The corporate terms of service has not been accepted. To accept, go to https://business.facebook.com/ads/manage/customaudiences/tos.php
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
272This Ads API call requires the user to be admin of the application
2633This shared login is disabled. Go to Ads Manager for more information.
273This Ads API call requires the user to be admin of the ad account

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.