Lookalike Audiences: API Implementation Guide

What Are Lookalike Audiences?

Lookalike audiences are Meta's way of finding new people who resemble your existing customers. You provide a source audience (your best customers, recent purchasers, high-LTV users), and Meta's algorithm finds users in the broader population who share similar characteristics -- demographics, interests, behaviors, and engagement patterns.

Lookalikes are one of the most effective prospecting tools in digital advertising. They consistently outperform interest-based targeting because they use real behavioral data rather than declared interests.

How Lookalike Audiences Work

The process has three steps:

1. Source audience analysis. Meta examines the users in your source audience and identifies common traits -- not just demographics, but thousands of behavioral signals including purchase patterns, app usage, content engagement, and device behavior.

2. Population scoring. Meta scores the entire addressable population in your target country against these traits, ranking users by how closely they match your source audience.

3. Audience creation. Based on your specified ratio (1-10%), Meta selects the top-scoring users. A 1% lookalike in the United States includes approximately 2.4 million people.

Choosing the Right Source Audience

The quality of your source audience determines the quality of your lookalike. Here is a hierarchy from best to worst:

Source Audience	Quality	Why
Top 25% customers by LTV	Excellent	Optimizes for your highest-value behavior
All purchasers (last 180 days)	Very Good	Broad but conversion-focused signal
Add-to-cart users (last 30 days)	Good	High intent, fresher signal
Website visitors (last 30 days)	Moderate	Broad, includes non-converters
Page/profile engagers	Moderate	Engagement does not always mean purchase intent
Video viewers (50%+)	Fair	Awareness-level signal

Building a High-Quality Source

Create a customer list audience with your best customers:

// Step 1: Create a source audience of high-LTV customers
const sourceAudience = await fetch("https://api.xyloapi.dev/v1/audiences", {
  method: "POST",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "act_123456789",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Source - Top Customers by LTV",
    type: "customer_list",
    description: "Customers with lifetime value above $500",
    customer_file_source: "user_provided_only",
    customers: topCustomers.map((c) => ({
      email: c.email,
      phone: c.phone,
      first_name: c.firstName,
      last_name: c.lastName,
    })),
  }),
});

const { data: source } = await sourceAudience.json();
console.log(`Source audience created: ${source.id}, ~${source.approximate_count} matched users`);

Wait for the source audience to finish processing (30 minutes to a few hours) before creating the lookalike.

Source Audience Size Guidelines

• Minimum: 100 matched users (Meta's hard requirement)
• Recommended minimum: 1,000 matched users (better signal quality)
• Sweet spot: 2,000-50,000 matched users
• Diminishing returns: Above 50,000, the additional data provides marginal improvement

A common mistake is using too large a source audience. If you upload your entire customer database (including one-time buyers who never returned), the lookalike will optimize for "anyone who might buy once" rather than "people like your best customers."

Creating Lookalike Audiences via API

Single Country Lookalike

const response = await fetch("https://api.xyloapi.dev/v1/audiences", {
  method: "POST",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "act_123456789",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Lookalike - Top Customers US 1%",
    type: "lookalike",
    source_audience_id: source.id,
    country: "US",
    ratio: 0.01,
  }),
});

const { data: lookalike } = await response.json();
console.log(`Lookalike created: ${lookalike.id}`);

Understanding Ratio Sizing

The ratio controls what percentage of the target country's population is included:

Ratio	US Audience Size	Similarity to Source	Best For
1% (0.01)	~2.4 million	Highest	Bottom-of-funnel, conversion campaigns
2% (0.02)	~4.8 million	Very high	Balanced reach and precision
3-5% (0.03-0.05)	~7-12 million	High	Mid-funnel, consideration campaigns
6-10% (0.06-0.10)	~14-24 million	Moderate	Top-of-funnel, awareness campaigns

Start with 1% for direct response campaigns. If your 1% lookalike delivers strong results and you want more reach, create a 2% or 3% version.

Multiple Ratio Strategy

A common strategy is to create multiple lookalikes at different ratios and test them in separate ad sets:

const ratios = [0.01, 0.02, 0.05];

const lookalikes = await Promise.all(
  ratios.map(async (ratio) => {
    const response = await fetch("https://api.xyloapi.dev/v1/audiences", {
      method: "POST",
      headers: {
        "x-api-key": process.env.XYLO_API_KEY!,
        "x-ad-account": "act_123456789",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: `Lookalike - Top Customers US ${ratio * 100}%`,
        type: "lookalike",
        source_audience_id: source.id,
        country: "US",
        ratio,
      }),
    });
    return response.json();
  })
);

for (const { data } of lookalikes) {
  console.log(`Created: ${data.name} (~${data.approximate_count} users)`);
}

Then create ad sets for each, using the same creative, and let Meta's delivery optimization find the best performers.

Multi-Country Lookalikes

For businesses advertising internationally, you can create separate lookalikes for each target country:

const countries = ["US", "GB", "CA", "AU", "DE"];

for (const country of countries) {
  await fetch("https://api.xyloapi.dev/v1/audiences", {
    method: "POST",
    headers: {
      "x-api-key": process.env.XYLO_API_KEY!,
      "x-ad-account": "act_123456789",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: `Lookalike - Top Customers ${country} 1%`,
      type: "lookalike",
      source_audience_id: source.id,
      country,
      ratio: 0.01,
    }),
  });
}

Each country's lookalike is built independently. The algorithm finds people in that specific country who resemble your source audience, accounting for local behavioral patterns.

Using Lookalikes in Campaigns

Basic Targeting

await fetch("https://api.xyloapi.dev/v1/ad-sets", {
  method: "POST",
  headers: {
    "x-api-key": process.env.XYLO_API_KEY!,
    "x-ad-account": "act_123456789",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Prospecting - Lookalike 1%",
    campaign_id: campaignId,
    daily_budget: 100.00,
    targeting: {
      custom_audiences: [{ id: lookalike.id }],
      geo_locations: { countries: ["US"] },
    },
    status: "paused",
  }),
});

Exclude Existing Customers

Always exclude your source audience and existing customers from lookalike campaigns to avoid paying to reach people who already converted:

targeting: {
  custom_audiences: [{ id: lookalike.id }],
  excluded_custom_audiences: [
    { id: source.id },          // source audience
    { id: allCustomersId },     // all customers
  ],
  geo_locations: { countries: ["US"] },
}

Layer with Demographics

Narrow your lookalike with demographic constraints when you have a well-defined customer profile:

targeting: {
  custom_audiences: [{ id: lookalike.id }],
  age_min: 25,
  age_max: 54,
  genders: [2],  // female
  geo_locations: { countries: ["US"] },
}

Be careful with over-narrowing. The lookalike algorithm already identified similar people. Adding too many constraints can reduce your audience to the point where Meta cannot optimize delivery effectively.

Monitoring Lookalike Performance

Track these metrics to evaluate your lookalike audiences:

const campaigns = await fetch(
  "https://api.xyloapi.dev/v1/campaigns?date_preset=last_7d",
  {
    headers: {
      "x-api-key": process.env.XYLO_API_KEY!,
      "x-ad-account": "act_123456789",
    },
  }
).then((r) => r.json());

// Compare lookalike performance by ratio
for (const campaign of campaigns.data) {
  if (campaign.name.includes("Lookalike")) {
    const { spend, conversions, cost_per_conversion, ctr } = campaign.insights;
    console.log(
      `${campaign.name}: CPA $${cost_per_conversion}, CTR ${ctr}%, ` +
      `${conversions} conversions on $${spend} spend`
    );
  }
}

Key indicators:

• CPA by ratio. 1% should have the lowest CPA. If 2% beats 1%, your source audience may be too small.
• CTR differences. Higher CTR in smaller ratios confirms better audience quality.
• Frequency. If frequency exceeds 3-4x per week, the audience may be saturated. Expand to a larger ratio.

Refreshing Lookalike Audiences

Lookalike audiences do not automatically update when your source audience changes. If you add new customers to your source audience, the existing lookalike still uses the original data.

To keep lookalikes fresh:

1. Update your source audience monthly with new customer data
2. Create a new lookalike from the updated source
3. Swap the new lookalike into your ad sets
4. Archive the old lookalike after a transition period

// Monthly lookalike refresh workflow
async function refreshLookalike(sourceId: string, oldLookalikeId: string) {
  // Create new lookalike from updated source
  const response = await fetch("https://api.xyloapi.dev/v1/audiences", {
    method: "POST",
    headers: {
      "x-api-key": process.env.XYLO_API_KEY!,
      "x-ad-account": "act_123456789",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: `Lookalike - Top Customers US 1% (${new Date().toISOString().slice(0, 7)})`,
      type: "lookalike",
      source_audience_id: sourceId,
      country: "US",
      ratio: 0.01,
    }),
  });

  const { data: newLookalike } = await response.json();
  console.log(`New lookalike: ${newLookalike.id}. Update ad set targeting to use this ID.`);
}

Getting Started

1. Build your source audience. Upload your highest-value customers through the Xylo audiences API.
2. Start with 1% in your primary market. Create a single 1% lookalike in your largest country.
3. Test in a dedicated ad set. Give the lookalike its own budget to isolate performance.
4. Expand gradually. If 1% works, test 2% and 3%. Add more countries as you scale.
5. Refresh monthly. Keep your source audience current for the best lookalike quality.

For the full audiences API reference, read our Custom Audiences guide. To automate audience management with AI, see building AI agents for ads.

Sign up for Xylo and start building lookalike audiences today.