Manage custom audience (create / update / delete) (`adsap_manage_custom_audience`)

Platform: Meta · Read or write: Write · Plan: Early Access · Consumes a task: Yes · Preview supported: Yes

What it does

Creates, updates or deletes a rule-based Meta custom audience: website visitors, Instagram or Facebook engagers, lookalikes of an existing audience, or app users. The first call is a preview; ask again to apply. Deleting is permanent and pauses any ad set that uses the audience, and the preview first lists the ads that use it.

When to use it

Use it to build a retargeting or lookalike audience, then target it in adsap_create_ad_sets with custom_audiences.
It supports a preview call, and dry_run defaults to true. A preview writes nothing and does not use a task.
A website audience needs a pixel ID from adsap_list_meta_assets. An engagement audience needs the Instagram account ID from the same tool.
A lookalike needs origin_audience_id, the ID of a seed audience from adsap_list_custom_audiences. ratio runs from 0.01 to 0.20.
update and delete need custom_audience_id. Before a delete, adsap_get_custom_audience_ads shows which ads use the audience.
retention_seconds in the rule sets how long people stay in the audience, up to 180 days.

Worked example

You ask

“Preview a website audience for act_1234567890: everyone who visited a pricing page in the last 30 days.”

The assistant calls `adsap_manage_custom_audience`


{
  "action": "create",
  "ad_account_id": "act_1234567890",
  "audience_type": "website",
  "name": "Pricing page visitors, 30 days",
  "rule": "{\"inclusions\":{\"operator\":\"or\",\"rules\":[{\"event_sources\":[{\"type\":\"pixel\",\"id\":\"120210000000003\"}],\"retention_seconds\":2592000,\"filter\":{\"operator\":\"and\",\"filters\":[{\"field\":\"url\",\"operator\":\"i_contains\",\"value\":\"pricing\"}]},\"template\":\"VISITORS_BY_URL\"}]}}",
  "dry_run": true
}

Adsap returns

The field names are the ones Adsap returns. The values are examples.


{
  "ok": true,
  "dry_run": true,
  "action": "create",
  "would": {
    "method": "POST",
    "endpoint": "/act_1234567890/customaudiences",
    "params": {
      "name": "Pricing page visitors, 30 days",
      "rule": "{\"inclusions\":{\"operator\":\"or\",\"rules\":[{\"event_sources\":[{\"type\":\"pixel\",\"id\":\"120210000000003\"}],\"retention_seconds\":2592000,\"filter\":{\"operator\":\"and\",\"filters\":[{\"field\":\"url\",\"operator\":\"i_contains\",\"value\":\"pricing\"}]},\"template\":\"VISITORS_BY_URL\"}]}}"
    }
  }
}

How to read it

This is a preview. Nothing was written to Meta. would shows the request Adsap is ready to send: the method, the endpoint on your ad account, and the params. Check name and the rule here. The rule is a text value that holds JSON, which is why its quotes are escaped. 2592000 seconds is 30 days. The pixel ID in event_sources comes from adsap_list_meta_assets. The response also carries a human_readable_summary sentence.

After you confirm, the assistant sends the same call with dry_run set to false. That answer has an audience object read back from Meta, with its id, name and subtype.

Parameters

Descriptions are shortened from the tool schema. Your assistant sees the full text.

Name	Type	Required	Description
`action`	one of `create`, `update`, `delete`	Yes	What to do: “create” a new rule-based audience, “update” an existing one’s name/description/rule, or “delete” one permanently.
`ad_account_id`	string	Yes	act_<digits>. The ad account that owns (or will own) the custom audience. Used for ownership, workspace resolution, and Meta API budget.
`audience_type`	one of `website`, `engagement`, `lookalike`, `app`	No	Required for action=create. “website” = pixel/site visitors (WCA), “engagement” = people who engaged with your Instagram/Facebook (ECA), “lookalike” = people similar to an existing audience (LAL), “app” = mobile app users (MACA).
`name`	string	No	Required for action=create. The audience name shown in Ads Manager.
`rule`	string	No	Required for create when audience_type is website/engagement/app (NOT lookalike). A JSON-ENCODED STRING (not an object). Structure: {“inclusions”:{“operator”:“or”,“rules”:[<rule>]}} (optional top-level “exclusions” with the same shape).
`description`	string	No	Optional description for the audience (create or update).
`prefill`	boolean	No	Optional (website/engagement/app create). TRUE backfills the audience with historical data. Defaults to Meta’s default (true).
`origin_audience_id`	string	No	Required for create when audience_type=lookalike. The numeric id of the SEED audience to model on (a WEBSITE/ENGAGEMENT/APP/CUSTOM audience: NOT another lookalike). Get it from adsap_list_custom_audiences.
`ratio`	number	No	Lookalike only. Share of the population to match, 0.01 (1%, closest/smallest) to 0.20 (20%, broadest/largest). Defaults to 0.01.
`lookalike_country`	string	No	Lookalike only. ISO country code (e.g. “US”, “FR”, “GB”). DEPRECATED BY META (v26 / all versions from 2026-09-01): the API silently ignores it and creates a countryless parent lookalike…
`custom_audience_id`	string	No	Required for action=update and action=delete. The numeric id of the existing custom audience. Get it from adsap_list_custom_audiences.
`dry_run`	boolean	No	Preview only: the request is validated and the resolved payload returned, nothing is created or changed.

Example prompts

“Create a website audience of everyone who visited the pricing page in the last 30 days.”
“Build a 1% lookalike of my Purchasers audience for the US.”
“Preview deleting the old Engagers 2024 audience and tell me which ads use it.”

Notes

Customer list uploads (hashed emails or phone numbers) are not supported here. The account must accept Meta’s Custom Audience terms once before the first audience is created.

adsap_get_custom_audience_ads: List the ads that use/target a given custom audience (live from Meta): each with its ad set and campaign id.
adsap_list_custom_audiences: List custom audiences and saved audiences in a Meta ad account.

Guide

Read Audiences and targeting for the workflow around this tool, and the Tool reference for every tool.

The Meta Ads MCP server page shows how to connect Meta Ads to Claude, ChatGPT or Perplexity.

Manage custom audience (create / update / delete) (adsap_manage_custom_audience)