Target people most like your established customers. Lookalike audiences take several sets of people as "seeds" then Facebook builds an audience of similar people. You can use lookalikes for any business objective: Targeting people similar your customers for fan acquisition, site registration, off-Facebook purchases, coupon claims, or simply to drive awareness of a brand.
Seed audiences can be:
Facebook refreshes members in a lookalike every 3 days if the lookalike belongs to an adgroup.
Lookalike audiences can take 1-6 hours to fully populate. While audiences populate, you can create and run ad sets targeting the audience. Once the audience is ready, Facebook delivers to people populated in the audience and ads delivery will catchup and work as normal. See Delivery Status. Create a new lookalike audience at: https://graph.facebook.com/{API_VERSION}/act_{AD_ACCOUNT_ID}/customaudiences
.
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();
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.11/act_<AD_ACCOUNT_ID>/customaudiences
To create lookalike audiences with PHP Ads SDK or Python Ads SDK, use CustomAudience
.
The response contains:
Name | Description |
---|---|
type: integer | ID of lookalike audience |
If you have a Custom Audience with at least 100 people, you can build lookalike audiences based on it. This includes Custom Audiences for your Website and Custom Audiences for your Mobile App.
Name | Description |
---|---|
type: string | Required. Custom Audience name |
type: long | Required. ID of Custom Audience. Origin audiences must have at least 100 members. |
type: array | Required. See description below. |
type: string | Required. Set either
|
type: float | Optional. Start percentage for lookalike. For example, |
type: float | Required. Set either
|
type: boolean | Optional. At least 100 seed audience members from a country. If not, |
type: string | Required. Set Find lookalike audience members in this country |
type: array | Required. Either Find audience members in these locations. List of countries or country groups such as |
type: array | Required. At least one entry under Include these locations |
type: array of strings | Optional. Target countries. Array of country codes, see Targeting Search API, Countries.
Example: |
type: array of strings | Optional. Target countries in global regions and free trade areas. Array of country group codes. For full options, see Targeting, Location, |
type: array | Optional. Locations to exclude |
type: array of strings | Optional. Same as |
type: array of strings | Optional. Same as |
Optimize your audience for "Similarity" or "Greater reach".
Instead of using types you can manually set ratio
to represent the top x% of the audience in the selected country. ratio
should be from 1%-20% and in intervals of 1%.
Facebook has campaign and ad set conversion lookalikes to target people similar to those converting from previous or current campaigns or ad sets; for example, campaigns or ads that are optimizing for conversions. We measure conversions based on a campaign or ad set type in Conversion Specs. For example, target people that took action on your website or installed your app within 28 days of clicking your ad.
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();
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.11/act_<AD_ACCOUNT_ID>/customaudiences
You need at least 100 unique conversions from your campaigns or ad sets. More converters result in a better predictive model and we suggest 200 or more members who converted. You should also select campaigns or ad sets with similar objectives.
To create this lookalike, specify one or more of your campaigns or ad sets. For example, specify one campaign and two ad sets of another campaign.
Facebook uses up to 180 days of past conversion data and identifies people converting on your campaigns and ad sets as examples. We train prediction model then create a lookalike audience. Facebook constantly updates the underlying prediction model as campaigns or ad sets get new conversions.
Name | Description |
---|---|
type: array | Required. See description below. |
type: array of integers | Required. Array of ad object ids. People who convert on these ads are used to model a lookalike. One or more campaign IDs or ad set IDs, or a mix of them. |
type: string | Required.
|
type: string | Required. Country to find lookalike members. |
type: boolean | Optional. At least 100 seed audience members from a country. If not, |
type: float | Optional. Start percentage for lookalike. For example, |
type: float | Required. Range of |
Currently, the following campaign conversion types are eligible for Lookalike Audiences:
Create a lookalike audience based on people who like your Page:
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();
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.11/act_<AD_ACCOUNT_ID>/customaudiences
Name | Description |
---|---|
type: array | Required. See description below. |
type: int | Required. Facebook ID of the page whose fans will be used for the lookalike |
type: string | Required.
|
type: string | Required. The country to find the lookalike people. The default is 'US' |
type: boolean | Optional. You need at least 100 seed audience members from a country. If this minimum is not satisfied, |
type: float | Optional. 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 |
type: float | Required. Range 0.01-0.20. How much of the country the lookalike should target. |
Targeting lookalikes is the same as targeting Custom Audiences. See Custom Audiences, Targeting. This also applies for exclusion targeting and conjunctive AND
targeting. To target when you create an ad:
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.11/act_<AD_ACCOUNT_ID>/adsets
More examples at Targeting Specs.
Get details on custom audiences used to create lookalikes as well as lookalikes. We return the same fields as Custom Audiences. Below is a sample response for a Custom Audience used to create lookalikes. lookalike_audience_ids
specifies which lookalike audiences were generated from this 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 },
Lookalike audiences contain a subtype
of 2. We also return lookalike_spec
, an array in this format:
Name | Description |
---|---|
type: string |
|
type: float | Returned if |
type: float | Multiple of |
type: string | Country code |
type: array | See description below. |
type: boolean |
|
type: int | Origin ID |
type: string | Origin name |
type: string |
|
type: array of strings | All countries used to create audience |
Another audience below where subtype
is LOOKALIKE
:
{ "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 },
After you create a lookalike audience we return a Custom Audience ID. It can take about one hour to fully populate an audience. You can get the status at: /{lookalike_audience_ID}?fields=delivery_status
. This returns a JSON response with delivery_status
or code 200 if an audience populates:
"delivery_status": { "code": 200, "description": "This audience is ready for use." },
For testing, you should check the status of the list with Ads Manager.
To delete a lookalike audience, you do the same as you do for Custom Audiences.
A Lookalike audience is considered inactive when it has not been used in active ads for 90 days. Inactive lookalike audiences have different approximate_count
, operation_status
, and delivery_estimate
.
Field | Changes for Inactive Lookalikes |
---|---|
| You are not able to retrieve a size. A call for this field returns |
|
|
| You are not able to retrieve a delivery estimate. A call for this field returns |
| When an audience's |
You can still start a campaign using an inactive lookalike audience. The reach estimate information is available after your new ad gets published.
For all advertisers beginning June 8, 2021 and going forward, we will automatically be moving audiences to the “Expiring Audience” stage once they have been inactive for over two years. This means that once an audience meets the threshold of not being used in an active ad set for over two years, it will be automatically flagged as an “Expiring Audience”, and the delete_time
field will be marked with the estimated deletion time (i.e., 90 days from the time of flagging) when the audience is scheduled to be deleted.
You will then be able to either proactively delete the audience or use the audience in an active ad set to prevent deletion. You can see which of your audiences are in the expiring stage at any time by filtering on their operation_status
or delete_time
fields.
For more information, see the Custom Audiences Overview documentation.
UPDATED APRIL 28, 2021: The removal of thelocation_spec
and country
parameters from lookalike audience creation is currently delayed. Updates on when this change will go into effect will be forthcoming.
We will remove the location_spec
and country
parameters from lookalike audience creation. The location for the lookalikes will be defined by the country location in the campaign’s targeting specification. The target location won’t be a part of the lookalike audience specification. The reach estimate of the campaign using a newly created lookalike will be populated only in a few hours after the ad being published.
There will be no impact on existing campaigns given this change. This requirement will only impact new and edited campaigns.
We will automatically convert legacy lookalike audiences into new lookalikes without target locations.
Endpoint: act_{AD_ACCOUNT_ID}/customaudiences
Example Request
curl POST \ -F 'name=My lookalike audience' \ -F 'subtype=LOOKALIKE' \ -F 'origin_audience_id=<SEED_AUDIENCE_ID>' \ -F ‘lookalike_spec={ "is_financial_service":false, "allow_international_seeds":true, "ratio":0.01, "type":"custom_ratio"} ’}\ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/customaudiences
The following parameters will be ignored if passed during creation:
lookalike_spec.country
lookalike_spec.location_spec
lookalike_spec.location_spec.geo_locations
lookalike_spec.location_spec.geo_locations.countries
lookalike_spec.location_spec.geo_locations.country_groups
lookalike_spec.location_spec.excluded_geo_locations
lookalike_spec.location_spec.excluded_geo_locations.countries
lookalike_spec.location_spec.excluded_geo_locations.country_groups
Endpoint: act_{AD_ACCOUNT_ID}?fields=approximate_count
There will be no size associated with new lookalike audiences, and the approximate_count
field will return -1
for all lookalike audiences.
Example Response
{ "approximate_count": -1, "id": "6126486105659", }
Endpoints:
{AD_ACCOUNT_ID}?fields=delivery_status
{AD_ACCOUNT_ID}?fields=operation_status
The delivery_status
field for old lookalike audiences with location specifications will return a code 400
with a This audience is disabled.
description. For new lookalike audiences it will return a code 200
response.
The operation_status
field will return a retirement notification for old lookalike audiences with location specifications. For new lookalike audiences it will return a code 200
and Normal
description response.
See Custom Audiences for more information about these fields.
We will automatically upgrade ads to use new lookalikes if the targeting of the existing campaigns containing the legacy lookalike is edited. The legacy lookalike will no longer be available for use in newly created ad campaigns.
With location specifications removed from lookalike audience creation, you will need to set location targets during Ad Set creation. Attempting to create an Ad Set without location targeting will result in an error.
All the above changes will also be applicable when audiences are included in excluded_custom_audiences
, flexible_spec
, and exclusions
in the campaign.
Endpoint: act_{AD_ACCOUNT_ID}/adsets
Example Request
curl POST \ -F 'targeting={ "geo_locations":{ "countries":["US"], }, "age_min":25, "age_max":40, "custom_audiences":[{"id": <CUSTOM_AUDIENCE_ID>}] ‘}\ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets
Attempting to create an Ad Set without location targeting will result in an error.
{ "error": { "message": "Invalid parameter", "type": "FacebookApiException", "code": 100, "error_data": { "blame_field_specs": [["targeting" ] ] }, "error_subcode": 192342134, "is_transient": false, "error_user_title": "Missing Location while using Lookalike", "error_user_msg": "You need to use a location with your lookalike audience.", "fbtrace_id": "F78cCCJoZPx" }, "__fb_trace_id__": "F78cCCJoZPx", "__www_request_id__": "AcwlIc7_uK5uTXjzjIa38yc" }
If you try to edit an Ad Set containing a shared legacy lookalike and don’t have a corresponding new lookalike in the owning ad account, an error will occur. Request the owning ad account share the new lookalike audience with you to resolve the issue.
{ "error": { "message": "Invalid parameter", "type": "FacebookApiException", "code": 100, "error_data": { "blame_field_specs": [["targeting" ] ] }, "error_subcode": 192342135, "is_transient": false, "error_user_title": "", "error_user_msg": "Please ask the owner of the audience 1234 to share the new lookalike which does not contain location with you. You will be able to use the new audience" "fbtrace_id": "F78cCCJoZPx" }, "__fb_trace_id__": "F78cCCJoZPx", "__www_request_id__": "AcwlIc7_uK5uTXjzjIa38yc" }
During the rollout period of these changes, sharing lookalikes between ad accounts in the rollout and ad accounts not in the rollout is not supported via the API. Please use Audience Manager to handle the sharing. After May 24, 2021, you can continue to use sharing via API in the following developer document to share new lookalike audiences between ad accounts.
Endpoint: {AD_ACCOUNT_ID}/adaccounts?adaccounts={SHARED_TO_AD_ACCOUNT_ID}
Endpoints:
act_{AD_ACCOUNT_ID}/reachestimate
act_{AD_ACCOUNT_ID}/delivery_estimate
These endpoints will return a new targeting_status
parameter with one of the following descriptions:
lookalike_container_without_country
— A new lookalike does not have a country specified in the campaign targeting. A country is needed to see the estimated users number.lookalike_container_without_delivery_lookalike
— A new lookalike does not have a corresponding backend lookalike. The new lookalike needs to be used in an Ad Set for it to actually have reach.none
— There is no issue with the reach.The reachestimate
endpoint will return -1
for the users
parameter the first time a new lookalike audience and country target is used; thereafter the estimated user count will be returned.
The estimate_dau
and estimate_mau
parameters will return -1
for the users
parameter the first time a new lookalike audience and country target is used; thereafter the estimated user count will be returned..
Example Responses
// Reach estimate response { "users": -1, "estimate_ready": true, "targeting_status": "lookalike_container_without_delivery_lookalike" } // Delivery estimate response { "data": [{ "daily_outcomes_curve": [{ "spend": 0, "reach": 0, "impressions": 0, "actions": 0 }], "estimate_dau": -1, "estimate_mau": -1, "estimate_ready": true , "targeting_status": "lookalike_container_without_delivery_lookalike" }] }
UPDATED APRIL 28, 2021: The removal of thelocation_spec
and country
parameters from lookalike audience creation is currently delayed. Updates on when this change will go into effect will be forthcoming.
UPDATED APRIL 28, 2021: The removal of thelocation_spec
and country
parameters from lookalike audience creation is currently delayed. Updates on when this change will go into effect will be forthcoming.
During the period between Marketing API v10 and v11, sharing lookalikes between ad accounts in the rollout and ad accounts not in the rollout is not supported via the API. Please use Audience Manager to handle the sharing. After the release of Marketing API v11, you can continue to use sharing via the API to share new lookalike audiences between ad accounts.