account | DynamicAccount | Yes | - | Select Meta Ads account, ask the user for it if not provided |
name | string | Yes | - | Name for the custom audience |
description | string | No | - | Optional audience description |
audience_type | string or SelectableOption | Yes | - | Audience type to create. Use CUSTOMER_LIST for an empty customer-file audience container (upload users separately). Use WEBSITE for Meta Pixel retargeting such as URL visitors or pixel events. Use ENGAGEMENT for Instagram profile, Facebook Page, video, or lead form engagement; the backend builds the Meta rule from engagement_source_type, engagement_source_id, and engagement_type. |
customer_file_source | string or SelectableOption | No | USER_PROVIDED_ONLY | Required for CUSTOMER_LIST audiences. Describes the source of the customer data. |
pixel_id | string | No | - | Required for WEBSITE audiences when website_rule_type is URL_CONTAINS or EVENT. Numeric Meta Pixel ID used by the backend to build event_sources inside rule. For CUSTOM_RULE, include event_sources inside rule instead. |
retention_days | integer | No | 30 | Website audience lookback window in days, 1-180. Used by URL_CONTAINS and EVENT to build retention_seconds inside rule. For CUSTOM_RULE, include retention_seconds inside rule instead. |
prefill | boolean | No | True | For WEBSITE or ENGAGEMENT audiences, ask Meta to include past matching activity when the source supports it. |
website_rule_type | string or SelectableOption | No | - | Required for WEBSITE audiences. Use URL_CONTAINS for visitors to pages whose URL contains a string. Use EVENT for people who fired one exact Meta Pixel event. Use CUSTOM_RULE only for advanced Meta website rule shapes that cannot be expressed by url_contains or event_name. |
url_contains | string | No | - | Required when website_rule_type=URL_CONTAINS. URL substring matched with Meta’s case-insensitive contains operator. Examples: ‘/pricing’, ‘/checkout’, ‘example.com/blog’. Backend builds a VISITORS_BY_URL rule with event=PageView plus this URL filter. Do not put a pixel event name here. |
event_name | string | No | - | Required when website_rule_type=EVENT. Exact Meta Pixel event name fired on the website, not an audience name or goal. Common standard events: PageView, ViewContent, AddToCart, InitiateCheckout, Lead, Purchase. Custom event names are allowed if the pixel sends that exact name. |
rule | object or string | No | - | Required only when website_rule_type=CUSTOM_RULE. Provide Meta’s website custom audience rule object as a dict/object or string. It must include event_sources, retention_seconds, and filter. Prefer url_contains or event_name for simple URL/event audiences. Use the current Audience Rules structure: {‘inclusions’: {‘operator’: ‘or’, ‘rules’: [{‘event_sources’: [{‘type’: ‘pixel’, ‘id’: ‘<PIXEL_ID>’}], ‘retention_seconds’: 2592000, ‘filter’: {‘operator’: ‘and’, ‘filters’: [{‘operator’: ‘or’, ‘filters’: [{‘field’: ‘url’, ‘operator’: ‘i_contains’, ‘value’: ‘/pricing’}]}]}}]}}. For VISITORS_BY_URL rules, include template=‘VISITORS_BY_URL’ and an event=PageView filter plus the URL filter group. For pixel event-only rules, use a direct event filter like {‘field’: ‘event’, ‘operator’: ‘eq’, ‘value’: ‘Lead’}. One-line URL example: {‘inclusions’: {‘operator’: ‘or’, ‘rules’: [{‘event_sources’: [{‘type’: ‘pixel’, ‘id’: ‘<PIXEL_ID>’}], ‘retention_seconds’: 2592000, ‘filter’: {‘operator’: ‘and’, ‘filters’: [{‘field’: ‘event’, ‘operator’: ‘eq’, ‘value’: ‘PageView’}, {‘operator’: ‘or’, ‘filters’: [{‘field’: ‘url’, ‘operator’: ‘i_contains’, ‘value’: ‘signin’}]}]}, ‘template’: ‘VISITORS_BY_URL’}]}}. Do not use old shorthand such as {‘url’: {‘i_contains’: ‘/pricing’}}. Do not use this for ENGAGEMENT audiences. |
engagement_source_type | string or SelectableOption | No | - | Required for ENGAGEMENT audiences. Source type for the Meta event source: INSTAGRAM_PROFILE, FACEBOOK_PAGE, VIDEO, or LEAD_FORM. |
engagement_source_id | string | No | - | Required for ENGAGEMENT audiences. Use the ID matching engagement_source_type: Instagram business profile ID, Facebook Page ID, video ID, or lead form ID. |
engagement_type | string or SelectableOption | No | - | Required for ENGAGEMENT audiences. Allowed by source: INSTAGRAM_PROFILE supports ANY_ENGAGEMENT, PROFILE_VISIT, POST_OR_AD_ENGAGEMENT, MESSAGE, SAVE; FACEBOOK_PAGE supports ANY_ENGAGEMENT, PAGE_VISIT, POST_OR_AD_ENGAGEMENT, MESSAGE, SAVE; VIDEO supports WATCHED_3_SECONDS, WATCHED_10_SECONDS, WATCHED_25_PERCENT, WATCHED_50_PERCENT, WATCHED_75_PERCENT, WATCHED_95_PERCENT; LEAD_FORM supports OPENED, OPENED_NOT_SUBMITTED, SUBMITTED. |
engagement_retention_days | integer | No | 365 | Engagement audience retention window in days. |
