Marketing API Version

Lookalike Audience

Overview

Lookalike audiences allow advertisers to target more people who look like their established customers. A lookalike audience uses several kinds of user set as a "seed" and an audience is built of similar users. Lookalike audiences can be used to support any business objective: Targeting people who are similar to sets of customers for fan acquisition, site registration, off-Facebook purchases, and coupon claims, or simply to drive awareness of a brand, and so on.

The seed can be of these types:

Lookalike audiences can take 1-6 hours to be fully populated once created. While the audience is populating you may create ad sets which target the new lookalike audience. Once the lookalike audience is ready, delivery to the included people will catchup and work as normal. Please read below about delivery status to find when an audience is fully populated.

Lookalike Audiences will automatically refresh every 3-7 days if they are assigned to adgroups. They will also refresh automatically if changes are made to the seed list.

Create

The endpoint to create a new lookalike audience is

 https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

To create a lookalike audience using PHP Ads SDK or Python Ads SDK, you can use CustomAudience class.

Response

The response of all create requests are all of the same format:

nametypedescription

id

integer

ID of lookalike audience


Custom Audience Lookalike

If you have a Custom Audience created already, with at least 100 people, you can have a lookalike audience based on that Custom Audience (including Custom Audiences for your Website and Custom Audiences for your Mobile App).

NameTypeDescriptionRequired

name

string

Name of your Custom Audience

Yes

origin_audience_id

long

The ID of origin Custom Audience. The origin audience you create must have a minimum size of 100.

Yes

lookalike_spec

array

See below

Yes

type

string

similarity or reach

yes - Either type or ratio should be set

starting_ratio

float

Starting percentage of the lookalike. For example, a starting_ratio of 0.01 and a ratio of 0.02 would create a lookalike from the 1% to 2% lookalike segment. The value of starting_ratio should always be less than that of ratio

no

ratio

float

Between 0.01-0.20 and increments of 0.01. Indicates the top x% of original audience in the selected country

yes - Either type or ratio should be set.

country

string

Country name - the country to find the lookalike people

yes

allow_international_seeds

boolean

You need at least 100 seed audience members from a country. If this minimum is not satisfied, allow_international_seeds set to true means Facebook finds this minimum number of seed audience members in another country. Defaults to false.

no

Types

Lookalike audience can be optimized for "Similarity" or "Greater reach".

  • When optimized for similarity, a lookalike audience will include the top 1% of people in the selected country who are most similar to the seed Custom Audience. The reach of the new audience will be smaller, but the match will be more precise.
  • When optimized for reach, a lookalike audience will include the top 5% of people in the selected country that are similar to the seed Custom Audience, but with a less precise match.

Instead of using types you can manually set a ratio value that represents the top x% of the audience in the selected country. The ratio value should be between 1%-20% and should be specified in intervals of 1%.

Example creation call for lookalike from a custom audience:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceSubtypes;

$lookalike = new CustomAudience(null, 'act_<AD_ACCOUNT_ID>');
$lookalike->setData(array(
  CustomAudienceFields::NAME => 'My lookalike audience',
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::LOOKALIKE,
  CustomAudienceFields::ORIGIN_AUDIENCE_ID => <SEED_AUDIENCE_ID>,
  CustomAudienceFields::LOOKALIKE_SPEC => array(
    'type' => 'similarity',
    'country' => 'US',
  ),
));
$lookalike->create();
echo $lookalike->id.PHP_EOL;
from facebookads.adobjects.customaudience import CustomAudience

lookalike = CustomAudience(parent_id='act_<AD_ACCOUNT_ID>')
lookalike.update({
    CustomAudience.Field.name: 'My lookalike audience',
    CustomAudience.Field.subtype: CustomAudience.Subtype.lookalike,
    CustomAudience.Field.origin_audience_id: '<SEED_AUDIENCE_ID>',
    CustomAudience.Field.lookalike_spec: {
        'type': 'similarity',
        'country': 'US',
    },
})

lookalike.remote_create()
print(lookalike)
curl \
  -F 'name=My lookalike audience' \
  -F 'subtype=LOOKALIKE' \
  -F 'origin_audience_id=<SEED_AUDIENCE_ID>' \
  -F 'lookalike_spec={"type":"similarity","country":"US"}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/customaudiences

Campaign/Ad Set Conversion Lookalikes

Facebook has built campaign/ad set conversion lookalike to help advertisers target people similar to converters of their previous or current campaigns or ad sets. Conversions are based on the type of previous campaign or ad set as defined in conversion specs, e.g. people that liked your Page or Place, RSVPed to your event, took an action on your website or installed your app within 28 days of clicking on your ad. For off Facebook conversions tracked by pixels, Conversion Data Lookalike is another choice.

You need to have at least 100 unique conversions across your campaigns or ad sets, to create a campaign/ad set conversion lookalike. More converters will result in a better predictive model and we suggest using 200 or more unique converters. It is also suggested that advertiser select campaigns or ad sets with similar objectives.

When creating campaign/ad set conversion lookalike, advertiser can specify one or more of their campaigns or ad sets. It can be a mix of them, like one campaign and two ad sets of another campaign.

We consider up to 180 days of past conversion data and use converters of these campaigns and ad sets as positive examples to train a prediction model and create a lookalike cluster.

We will keep updating the underlying prediction model as these campaigns or ad sets get newer converters.

NameTypeDescriptionRequired

lookalike_spec

array

See below

Yes

origin_ids

array of integers

An array of ad object ids whose converters will be used for the lookalike. Ids can one or more of campaign ID or ad set ID, or a mix of these.

yes

conversion_type

string

campaign_conversions - Indicates that this is a campaign conversion lookalike

yes

country

string

The country to find the lookalike people.

yes

allow_international_seeds

boolean

You need at least 100 seed audience members from a country. If this minimum is not satisfied, allow_international_seeds set to true means Facebook finds this minimum number of seed audience members in another country. Defaults to false.

no

starting_ratio

float

Starting percentage of the lookalike. For example, a starting_ratio of 0.01 and a ratio of 0.02 would create a lookalike from the 1% to 2% lookalike segment. The value of starting_ratio should always be less than that of ratio

no

ratio

float

Range 0.01-0.20. Indicates the top x% of original audience in the selected country.

yes

Example:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceSubtypes;

$lookalike = new CustomAudience(null, 'act_<AD_ACCOUNT_ID>');
$lookalike->setData(array(
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::LOOKALIKE,
  CustomAudienceFields::LOOKALIKE_SPEC => array(
    'origin_ids' => <CAMPAIGN_ID>,
    'starting_ratio' => 0.03,
    'ratio' => 0.05,
    'conversion_type' => 'campaign_conversions',
    'country' => 'US',
  ),
));
$lookalike->create();
echo $lookalike->id.PHP_EOL;
from facebookads.adobjects.customaudience import CustomAudience

lookalike = CustomAudience(parent_id='act_<AD_ACCOUNT_ID>')
lookalike.update({
    CustomAudience.Field.subtype: CustomAudience.Subtype.lookalike,
    CustomAudience.Field.lookalike_spec: {
        'origin_ids': '<CAMPAIGN_ID>',
        'starting_ratio': 0.03,
        'ratio': 0.05,
        'conversion_type': 'campaign_conversions',
        'country': 'US',
    },
})

lookalike.remote_create()
print(lookalike)
curl \
  -F 'subtype=LOOKALIKE' \
  -F 'lookalike_spec={ 
    "origin_ids": "<CAMPAIGN_ID>", 
    "starting_ratio": 0.03, 
    "ratio": 0.05, 
    "conversion_type": "campaign_conversions", 
    "country": "US" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/customaudiences

Conversion Data Lookalike

This kind of lookalike audience is based on the conversion data collected with conversion pixels on non-Facebook sites. Compared with campaign conversion lookalikes which is more flexible as the conversion there is defined by the objective of campaigns and/or ad sets, this lookalike audience is based on conversions off Facebook tracked by conversion pixels. This kind of lookalike audiences usually has good performance. Another advantage is that multiple conversion pixels can be used in the business flow, such as one for click and one for check-out, and you can create different audiences for each type of activities tracked.

NameTypeDescriptionRequired

name

string

Name of your Custom Audience

Yes

lookalike_spec

array

See below

Yes

type

string

similarity or reach

yes - Either type or ratio should be set

starting_ratio

float

Starting percentage of the lookalike. For example, a starting_ratio of 0.01 and a ratio of 0.02 would create a lookalike from the 1% to 2% lookalike segment. The value of starting_ratio should always be less than that of ratio

no

ratio

float

Between 0.01-0.20 and increments of 0.01. Indicates the top x% of original audience in the selected country

yes - Either type or ratio should be set

country

string

Country name - the country to find the lookalike people

yes

allow_international_seeds

boolean

You need at least 100 seed audience members from a country. If this minimum is not satisfied, allow_international_seeds set to true means Facebook finds this minimum number of seed audience members in another country. Defaults to false.

no

pixel_ids

array of integers

Conversion pixel IDs

yes

conversion_type

string

offsite

yes

An ad account using a shared pixel (i.e. of which they are not the owner) cannot use the pixel to create a lookalike audience.

Example:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceSubtypes;

$lookalike = new CustomAudience(null, 'act_<AD_ACCOUNT_ID>');
$lookalike->setData(array(
  CustomAudienceFields::NAME => 'My lookalike audience',
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::LOOKALIKE,
  CustomAudienceFields::LOOKALIKE_SPEC => array(
    'pixel_ids' => array(<PIXEL_ID>),
    'ratio' => 0.01,
    'conversion_type' => 'offsite',
    'country' => 'US',
  ),
));
$lookalike->create();
echo $lookalike->id.PHP_EOL;
from facebookads.adobjects.customaudience import CustomAudience

lookalike = CustomAudience(parent_id='act_<AD_ACCOUNT_ID>')
lookalike.update({
    CustomAudience.Field.name: 'My lookalike audience',
    CustomAudience.Field.subtype: CustomAudience.Subtype.lookalike,
    CustomAudience.Field.lookalike_spec: {
        'pixel_ids': ['<PIXEL_ID>'],
        'ratio': 0.01,
        'conversion_type': 'offsite',
        'country': 'US',
    },
})

lookalike.remote_create()
print(lookalike)
curl \
  -F 'name=My lookalike audience' \
  -F 'subtype=LOOKALIKE' \
  -F 'lookalike_spec={ 
    "pixel_ids": ["<PIXEL_ID>"], 
    "ratio": 0.01, 
    "conversion_type": "offsite", 
    "country": "US" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/customaudiences

Page Fan Lookalikes

You can create a lookalike audience based on people who like your Page (Page fans).

NameTypeDescriptionRequired

lookalike_spec

array

See below

Yes

page_id

int

Facebook ID of the page whose fans will be used for the lookalike

yes

conversion_type

string

page_like - Indicates that this is a page fan lookalike

yes

country

string

The country to find the lookalike people. The default is 'US'

yes

allow_international_seeds

boolean

You need at least 100 seed audience members from a country. If this minimum is not satisfied, allow_international_seeds set to true means Facebook finds this minimum number of seed audience members in another country. Defaults to false.

no

starting_ratio

float

Starting percentage of the lookalike. For example, a starting_ratio of 0.01 and a ratio of 0.02 would create a lookalike from the 1% to 2% lookalike segment. The value of starting_ratio should always be less than that of ratio

no

ratio

float

Range 0.01-0.20. How much of the country the lookalike should target.

yes

Example:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceSubtypes;

$lookalike = new CustomAudience(null, 'act_<AD_ACCOUNT_ID>');
$lookalike->setData(array(
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::LOOKALIKE,
  CustomAudienceFields::LOOKALIKE_SPEC => array(
    'ratio' => 0.01,
    'country' => 'US',
    'page_id' => <PAGE_ID>,
    'conversion_type' => 'page_like',
  ),
));
$lookalike->create();
echo $lookalike->id.PHP_EOL;
from facebookads.adobjects.customaudience import CustomAudience

lookalike = CustomAudience(parent_id='act_<AD_ACCOUNT_ID>')
lookalike.update({
    CustomAudience.Field.name: 'My lookalike audience',
    CustomAudience.Field.subtype: CustomAudience.Subtype.lookalike,
    CustomAudience.Field.lookalike_spec: {
        'ratio': 0.01,
        'country': 'US',
        'page_id': '<PAGE_ID>',
        'conversion_type': 'page_like',
    },
})

lookalike.remote_create()
print(lookalike)
curl \
  -F 'subtype=LOOKALIKE' \
  -F 'lookalike_spec={ 
    "ratio": 0.01, 
    "country": "US", 
    "page_id": "<PAGE_ID>", 
    "conversion_type": "page_like" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/customaudiences

Read

Reading the lookalike audiences for an account or individually returns the same fields as Custom Audiences - Please refer to that document for full details.

A lookalike audience can be identified as it contains a subtype of 2.

Additionally, the lookalike_spec, which is returned only for lookalike audiences, is an array of this format:

NameTypeDescription

type

string

similarity, reach or custom_ratio - Always returned

starting_ratio

float

This is returned if starting_ratio was specified during lookalike audience creation

ratio

float

Multiple of 0.01. This will be returned if the type is "custom_ratio"

country

string

Country code

allow_international_seeds

boolean

You need at least 100 seed audience members from a country. If this minimum is not satisfied, allow_international_seeds set to true means Facebook finds this minimum number of seed audience members in another country.

origin

array

See below

deleted

boolean

true, returned only when the origin is deleted

id

int

Origin ID

name

string

Origin name

type

string

custom_audience or conversion_pixel or page or app

A sample response when reading a Custom Audience from which lookalikes have been created is below; note the lookalike_audience_ids field which specifies which lookalike audiences were generated from this Custom Audience.

     {
      "id": "6006164557194",
      "account_id": 12345,
      "approximate_count": 816400,
      "lookalike_audience_ids": [
        6006183285954,
        6006183285955
      ],
      "name": "Boys Apparel",
      "parent_audience_id": 0,
      "parent_category": "Custom",
      "status": "ready",
      "subtype": "CUSTOM",
      "type": 4,
      "type_name": "Advertiser Generated",
      "time_updated": 1362439491
    }, 

An example lookalike audience response is below, note the subtype is LOOKALIKE in this case.

  {
   "id": "6006183285954",
   "account_id": 12345,
   "approximate_count": 1782100,
   "name": "Boys Apparel_lookalike_US_Similarity",
   "origin_audience_id": 6006567610735,
   "parent_audience_id": 0,
   "parent_category": "Custom",
   "status": "ready",
   "subtype": "LOOKALIKE",
   "type": 4,
   "type_name": "Advertiser Generated",
   "time_updated": 1362506552
  },  

Delivery Status

Once a lookalike audience is submitted for creation, a Custom Audience ID would be returned. It will take about one hour for the list to be fully populated. The status of the list is available when you query via API: /<lookalike_audience_ID>?fields=delivery_status. It will return a JSON response with delivery_status/code as 200 if the audience is ready:

  "delivery_status": {
    "code": 200, 
    "description": "This audience is ready for use."
  },

You can also check the status of the list with Ads Manager interface manually during testing or other non-program solution scenarios.

Delete

To delete a lookalike audience, the method is the same as for other Custom Audiences.

Targeting

Targeting a lookalike audience will work the same way as targeting a Custom Audience. For example see the targeting section of the Custom Audience doc. This also applies for exclusion targeting as well as conjunctive AND targeting.

The targeting segment during an ad set creation or update would be like the example below. More examples can be found at Targeting Specs.

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Targeting;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My AdSet',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
    TargetingFields::CUSTOM_AUDIENCES => array(
      array(
        'id' => <LOOKALIKE_AUDIENCE_ID>,
      ),
    ),
  )),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_ACTIVE,
));
from facebookads.adobjects.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.name: 'My Adset',
    AdSet.Field.daily_budget: 10000,
    AdSet.Field.campaign_id: '<CAMPAIGN_ID>',
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.link_clicks,
    AdSet.Field.billing_event: AdSet.BillingEvent.link_clicks,
    AdSet.Field.bid_amount: 150,
    AdSet.Field.daily_budget: 2000,
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
        'custom_audiences': [
            {
                'id': <LOOKALIKE_AUDIENCE_ID>,
            },
        ],
    },
})

adset.remote_create(params={
    'status': AdSet.Status.paused,
})
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My AdSet")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldCustomAudiences(Arrays.asList(
        new IDName()
          .setFieldId(<LOOKALIKE_AUDIENCE_ID>)
      ))
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
  )
  .setStatus(AdSet.EnumStatus.VALUE_ACTIVE)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My AdSet' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "custom_audiences": [{"id":"<LOOKALIKE_AUDIENCE_ID>"}], 
    "geo_locations": {"countries":["US"]} 
  }' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/adsets

Best Practices

  • The seed Custom Audience is recommended include at least 100 people. Making it as large as possible will help ensure there is enough data to find people similar to the list.
  • Lookalike audiences can be combined with the rest of Facebook's targeting to narrow down with additional demographics or interests.
  • Lookalike audiences can be used to target any kind of media, including Page post ads and domain ads.
  • If the seed audience has qualities like gender or geography built in, the lookalikes may not adhere to the same limits.