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 lists those ad sets first.
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 ad sets it would pause.”
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.
Related tools
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.