Graph API Version

    Ad Account Customaudiences

    Reading

    The custom audiences associated with the ad account.


    Note: To retrieve the IDs of lookalike audiences based on your custom audiences, use the lookalike_audience_ids field. See Lookalike Audiences - Managing Audiences for more information.

    Example

    Graph API Explorer
    GET /v19.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/v19.0/act_<AD_ACCOUNT_ID>/customaudiences
    If you want to learn how to use the Graph API, read our Using Graph API guide.

    Parameters

    ParameterDescription
    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
    pixel ID

    Optional.
    This param fetches audiences associated 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.

    Error Codes

    ErrorDescription
    100Invalid parameter
    80003There 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.
    200Permissions error
    368The action attempted has been deemed abusive or is otherwise disallowed

    Creating

    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.


    You can make a POST request to customaudiences edge from the following paths:
    When posting to this edge, a CustomAudience will be created.

    Example

    Graph API Explorer
    POST /v19.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/v19.0/act_<AD_ACCOUNT_ID>/customaudiences
    If you want to learn how to use the Graph API, read our Using Graph API guide.

    Parameters

    ParameterDescription
    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 CLAIM subtype.

    content_type
    enum {AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, HOME_LISTING, HOTEL, JOB, LOCAL_SERVICE_BUSINESS, LOCATION_BASED_ITEM, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER}

    Specifies a mandatory content type for TRAVEL claim objective.

    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 true, we fetch a custom audience instead of creating one when an identical custom audience already exists. Identical custom audiences must have same name, claim_objective, content_type, event_source_group/event_sources/sliced_event_source_group, inclusions, exclusions and rule.

    event_source_group
    numeric string or integer

    Specifies event source group for TRAVEL claim objective.

    event_sources
    array<JSON object>

    Specifies event sources for TRAVEL claim objective.

    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 true or false. true includes website traffic recorded prior to the audience creation, and false only includes 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 180 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, 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}

    Type of custom audience, derived from original data source.
    Note: COMBINATION subtype is only used by Ads Manager, and is not available through the API.

    Number of audiences limit for selected subtype:
    CUSTOM: 500
    LOOKALIKE: 10000

    use_in_campaigns
    boolean
    Default value: true

    use_in_campaigns

    Return Type

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

    Error Codes

    ErrorDescription
    200Permissions error
    100Invalid parameter
    2654Failed to create custom audience
    2663Terms of service has not been accepted. To accept, go to https://www.facebook.com/customaudiences/app/tos
    80003There 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.
    2667Your account permissions don't allow you to create a custom audience for this event source.
    190Invalid OAuth 2.0 Access Token

    Updating

    You can't perform this operation on this endpoint.

    Deleting

    You can't perform this operation on this endpoint.