Connect AI agents to Meta Ads

Retrieve advertising performance insights for an ad account, synchronously aggregated at the account, campaign, ad set, or ad level (level controls the grain even though the call is made on the account edge). Returns a data array of insight rows for the requested fields and breakdowns, plus paging.cursors for pagination. Use this for smaller or moderate reporting pulls; for large, high-cardinality, or long-date-range requests that risk timing out or being truncated, use metaads_account_insights_create_report_run instead and poll the async job. Subject to a dedicated insights rate limit reported via the x-fb-ads-insights-throttle response header (app_id_util_pct, acc_id_util_pct, ads_api_access_tier) -- back off as utilization nears 100%.

Retrieve a single Meta Ads ad by ID with the exact fields you request (e.g. status, creative, adset_id, campaign_id, review feedback). Returns one Ad object containing only the fields listed in fields; if fields is omitted, Meta returns just id. Use this to check one ad's delivery state, creative, or rejection reason by ID; use List Ads to browse or filter ads across an account instead. effective_status carries far more values than configured_status (e.g. PENDING_REVIEW, DISAPPROVED, PREAPPROVED, WITH_ISSUES) -- surface it separately when explaining why an ad isn't delivering, since configured_status alone (ACTIVE/PAUSED/DELETED/ARCHIVED) won't show a review or issue state.

Fetch performance metrics — impressions, clicks, spend, actions, and more — for a single ad, synchronously. Returns a data array of insight rows for the requested fields plus a paging.cursors object for pagination. Use this for smaller, ad-hoc reporting pulls on one ad; for broad, high-cardinality, or account-wide pulls, use an async insights report job instead of this synchronous call. Requires ads_read (or ads_management) permission; subject to a dedicated insights rate-limit reported via the x-fb-ads-insights-throttle response header.

Generate a preview iframe of how an existing Meta Ads ad will render in a specific placement/format. Returns a data array containing an AdPreview object with a body field: iframe HTML valid for only 24 hours. Use this to preview an ad that already exists in a given ad_format; use the account-level Generate Previews endpoint instead to preview a creative before an ad has been created. Requires ads_read (or ads_management) permission. width/height only resize the returned iframe's container, not the ad itself, and some creative/format combinations are unsupported and will error.

List ads under a Meta Ads ad account, optionally filtered by effective status or other conditions, with field selection. Returns an array of ad objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous). Use this to browse or audit ads in bulk, or to find the ad_id needed by Get Ad; pass an effective_status or filtering condition to scope large accounts. The same /ads edge also exists nested under a specific campaign or ad set (/{campaign_id}/ads, /{ad_set_id}/ads) -- to scope to one of those, filter with a campaign.id or adset.id condition here instead of a separate tool. Regular accounts cap at 5,000 non-deleted ads (50,000 for Bulk accounts).

List the ad creative(s) attached to a specific Meta Ads ad. Returns an array of AdCreative objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous). Most ads have exactly one creative, but dynamic/flexible creative ads can return several. Use this to inspect the creative(s) an ad actually uses without a separate lookup once you have its ad_id; use List Ad Creatives to browse all creatives in an ad account instead, or Get Ad Creative when you already have a creative ID. Requires ads_read permission.

List the leads generated by a specific ad, as an alternative to listing leads by form. Returns an array of lead objects (id, created_time, ad_id, form_id, field_data, and any other requested fields) plus cursor-based pagination info. Use this when you have an ad_id but not the form_id -- a lead form can be reused across multiple ads, so this returns only the leads tied to this one ad; go to the form's own leads edge instead if you need every lead across all ads using that form. Requires the caller to be a Page Admin (or granted access by one) for the Page behind this ad, plus the leads_retrieval, ads_management, pages_show_list, and pages_read_engagement permissions.

Retrieve details for a single ad account, such as status, currency, spend cap, balance, timezone, and business info. Returns the fields you request for the account; account_status and disable_reason come back as numeric enums (e.g. account_status 1=ACTIVE, 2=DISABLED) worth mapping to a human-readable label in your own logic. Use this to check account health, currency, or billing state before running campaigns; you must pass fields explicitly — Meta returns almost nothing without it. Requires ads_management or ads_read on the account; some fields need extra permissions (funding_source_details needs the MANAGE task, spend-related fields need ADVERTISE).

Get the current count of non-archived, non-deleted ads that are active or pending review on an ad account, to check usage against Meta's per-account ad ceilings. Returns data: an array with ads_running_or_in_review_count (one entry per Page when show_breakdown_by_actor is set). Use this before bulk-creating ads or ad sets to check headroom against the account's limit (6,000 ads for regular accounts, 50,000 for accounts with Bulk status; lower ceilings apply to ad sets and campaigns). Future-scheduled ads are excluded from the count, and a day-parted ad counts as active for the whole day it runs.

Get an estimated monthly-active-users reach range for a proposed (not-yet-created) ad set's targeting spec and optimization goal, before creating it. Returns estimate_mau_lower_bound and estimate_mau_upper_bound (the reach range), estimate_ready (false if the audience hasn't finished populating enough to estimate yet), and targeting_optimization_types. Use this to sanity-check a targeting_spec's reach before calling Create Ad Set; it is not available for inactive Lookalike Audiences.

Get a legacy lower/upper bound estimate of the number of people reachable by a targeting spec on this ad account. Returns users_lower_bound and users_upper_bound; both come back as -1 when an estimate isn't available for the given spec (e.g. one that includes a custom audience) -- that's not an error, just "no estimate". This is a legacy endpoint kept for back-compat; use metaads_adaccount_get_delivery_estimate instead for the current recommended reach estimate for a proposed ad set, since it also accounts for optimization_goal and promoted_object. targeting_spec's countries field is required. Watch for error 2641 if the spec includes/excludes a restricted location, and for rate-limit errors 613/80004 on accounts that call this frequently.

List the ad accounts a specific business-scoped user has been granted permission on, with the tasks permitted on each. Returns an array of ad account objects plus each one's permitted_tasks and access_type (OWNER or AGENCY), with cursor-based pagination. Use this to check one person's overall reach across accounts ("which accounts can this person touch"); use metaads_adaccount_list_users instead to check one account's full list of users. Requires a business-scoped user ID (not a plain Facebook user ID or /me) -- typically resolved first from metaads_business_list_business_users.

List the business or system users assigned to an ad account, along with each user's tasks (their unpacked permissions) and permitted_tasks (the tasks they could be assigned). Returns an array of user objects plus cursor-based pagination info (paging.cursors) and a summary.total_count. Use this to audit who has access to an ad account and at what task level -- MANAGE, ADVERTISE, ANALYZE, DRAFT, AA_ANALYZE -- since these task-based permissions are replacing legacy account roles. Requires the ID of the Business Manager business associated with the ad account, in addition to the account ID itself.

Retrieve a single ad creative's fields by id. Returns the creative's requested fields, such as object_story_spec, image/video reference, call_to_action_type, and status. Use this to inspect one known creative; use metaads_adcreative_list to browse or search the library instead. Always pass an explicit fields list — Meta's default field set here is minimal. Requires ads_management or ads_read permission, and the caller must be an admin of both the app and the ad account (Development-tier apps are rejected).

Generate an HTML/iframe preview of how a stored ad creative will render for a given placement. Returns data: an array of AdPreview objects, each containing an iframe body string that is only valid for about 24 hours. Use this to visually QA a creative in a specific placement (e.g. desktop feed vs. Instagram Stories) before it goes live; re-fetch to get a fresh iframe rather than caching one long-term. Not every creative/ad_format combination is supported -- e.g. some link or event ad creatives fail without a valid Page association.

List ad creatives stored in an ad account's creative library. Returns an array of creative objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous). Use this to browse or audit an account's creatives in bulk; pass fields and/or filtering to scope large libraries — Meta caps this edge at 50,000 total creatives, beyond which pagination is unavailable. Requires ads_management or ads_read permission, and the caller must be an admin of both the app and the ad account (Development-tier apps are rejected).

List the ad images stored in an ad account's image library. Returns each image's id, hash, temporary url, dimensions, status (ACTIVE/INTERNAL/DELETED), and the creatives that reference it. Use this to find an existing image's hash before building a creative with metaads_adcreative_create, or to audit the library; the returned url is temporary and should not be persisted or embedded in a creative. Requires ads_management or ads_read permission on the ad account.

Retrieve a single automated (ad) rule by ID with the exact fields you request (e.g. name, status, evaluation_spec, execution_spec, schedule_spec). Returns one AdRule object containing only the fields listed in fields; if fields is omitted, Meta returns just id and name. Use this to inspect one rule's full definition by ID; use List Ad Rules to browse or find rules across an account instead.

List the automated (ad) rules stored on an ad account. Returns an array of AdRule objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous). Use this to browse or audit an account's automation rules -- e.g. before creating a new rule to check for an existing similar one, or to find a rule's id for Get Ad Rule / Update Ad Rule.

List the execution history (audit log of past runs and actions taken) for an automated ad rule. Returns an array of history entries -- each shows the action Meta's rules engine took (e.g. PAUSED, CHANGED_BUDGET, EMAIL, NOT_CHANGED) and, depending on fields requested, a timestamp and the evaluation/execution results for the objects the rule governed -- plus cursor-based pagination info. Use this to confirm whether and when a rule actually fired, and what it did, after creating or updating it with metaads_adrule_create / metaads_adrule_update; use metaads_adrule_list to browse the rules themselves rather than their run history. Read-only edge -- there is no create/update/delete here, only reading past executions.

Retrieve a single Meta Ads ad set by ID with the exact fields you request (e.g. targeting, budget, schedule, status, optimization_goal, promoted_object). Returns one Ad Set object containing only the fields listed in fields; if fields is omitted, Meta returns just id. Use this to fetch one ad set's current configuration by ID; use List Ad Sets to browse or filter ad sets across an account instead. effective_status reflects rollups from the parent campaign (e.g. CAMPAIGN_PAUSED when the campaign itself is paused), which can differ from this ad set's own configured status.

Get an estimated audience reach range for an existing Meta Ads ad set, using its current targeting or a proposed replacement. Returns estimate_mau_lower_bound and estimate_mau_upper_bound (the reach range), estimate_ready (false if the audience hasn't finished populating enough to estimate yet), and targeting_optimization_types. Use this to sanity-check reach for an ad set that already exists; pass targeting_spec to preview a modified targeting without saving it to the ad set first. Use Get Delivery Estimate (the ad-account version) instead when the ad set doesn't exist yet. Estimates are directional approximations, not guarantees, and can return empty/zero for very narrow audiences. Requires ads_read or ads_management permission.

Fetch performance metrics -- spend, impressions, clicks, conversions, and more -- for a single Meta Ads ad set over a time range, synchronously. Returns a data array of insight rows for the requested fields plus a paging.cursors object for pagination. Use this for smaller, ad-hoc reporting pulls on one ad set; for wide date ranges, many breakdowns, or account-wide pulls that risk timing out, use the asynchronous insights report-run workflow instead of this synchronous call. Requires ads_read (or ads_management) permission; insights calls are rate-limited on a separate, tighter budget than other Marketing API calls, and data may be updated retroactively for a few days after the fact.

Get a human-readable text summary of an existing Meta Ads ad set's targeting spec. Returns an array of plain-English lines (e.g. geographic, age, and interest targeting) describing how the ad set's targeting_spec is being interpreted. Use this after Create Ad Set or Update Ad Set to confirm a targeting spec was interpreted as intended, or to show a readable summary in an agent UI; use Get Ad Set instead when you need the raw targeting JSON. Read-only; requires ads_read or ads_management permission.

List ad sets under a Meta Ads ad account, optionally filtered by effective status, campaign, or other conditions, with field selection. Returns an array of ad set objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous). Use this to browse or audit ad sets in bulk, or to find the ad_set_id needed by Get Ad Set / Update Ad Set; pass an effective_status or filtering condition to scope large accounts, or filter by campaign.id to see only one campaign's ad sets.

Retrieve a single Meta Pixel's fields by ID. Returns the requested pixel fields, such as name, code (the pixel's JS snippet), creation_time, last_fired_time, enable_automatic_matching, automatic_matching_fields, data_use_setting, and owner_business; without fields, only minimal defaults are returned. Use this to inspect one known pixel, e.g. after finding its id via metaads_adspixel_list. Always pass an explicit fields list -- Meta's default field set here is minimal. Requires ads_management or ads_read permission and access to the ad account or business that owns the pixel.

Get aggregated firing and match statistics for a Meta Pixel over a time window. Returns {data: [AdsPixelStatsResult...], paging}, broken down according to aggregation -- by event, device/browser, host/URL, custom data field, or hourly raw fire counts. Use this to monitor pixel health and volume rather than to browse individual events; pass event_source to separate browser-pixel firing from server-side (Conversions API) traffic. The retrieval window is capped at 7 days from the request time. Requires ads_management or ads_read permission and access to the ad account or business that owns the pixel.

List all Meta Pixels (AdsPixel objects) belonging to an ad account. Returns an array of pixel objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous); pass summary="total_count" to also get summary.total_count. Use this to discover an account's existing pixel(s) before calling metaads_adspixel_get or metaads_adspixel_create -- most ad accounts are limited to a single pixel, so this list is usually short. Requires ads_management or ads_read permission and access to the ad account.

List the users assigned to (with access to) a Meta Pixel. Returns an array of AssignedUser objects with their tasks (currently granted) and permitted_tasks (what's assignable), plus cursor-based pagination. Use this to audit who can manage a given pixel; assigning or removing users is done via Business Manager rather than this tool, since only GET is documented on this edge. Requires ads_management or ads_read permission and access to the ad account or business that owns the pixel.

List offline conversion event upload batches associated with this pixel or event set. Returns an array of upload-batch objects (fields like id, upload_tag, event_time_min/event_time_max, valid_entries, matched_entries, match_rate_approx, duplicate_entries, creation_time) plus cursor-based pagination info (paging.cursors, next/previous). Use this to audit or troubleshoot batch offline-event uploads made against this pixel/event-set ID; it isn't relevant if you send events in real time via the Conversions API instead of uploading offline batch files. Available since Marketing API v13.0. Read-only; requires the standard ads_read/ads_management access you already use to read this pixel.

List agencies or other businesses that a Meta Pixel has been shared with. Returns an array of Business objects the pixel is shared with, plus cursor-based pagination. Use this to check which partners already have delegated access to a pixel before sharing it further, or when auditing agency access on behalf of a client. Requires ads_management or ads_read permission and access to the ad account or business that owns the pixel.

Fetch a single ad video by id. Returns the requested fields, such as name, description, source (playback URL), picture (thumbnail), embed_html, format, created_time, and updated_time. Use this to inspect one known video's metadata after uploading it with metaads_advideo_create or finding it via metaads_advideo_list; always pass an explicit fields list since Meta's default field set here is minimal. Requires ads_management or ads_read permission, or the video otherwise being visible to the caller (e.g. via user_videos for a person-specific video).

List the videos in an ad account's video library, optionally filtered by dimensions, aspect ratio, length, or title. Returns an array of video objects plus paging info and a summary.total_count. Use this to find an existing video's id before building a creative with metaads_adcreative_create, or to audit the library. Requires ads_management or ads_read permission on the ad account.

Retrieve details of a specific Business Manager account -- name, verification status, timezone, primary Page, and related metadata. Returns the requested fields for a single Business object (id and name by default if fields is left blank). Use this to check a business's identity or verification status; use List Owned Ad Accounts, List Owned Pages, or List Owned Product Catalogs to see what it manages. Requires business_management permission, or an access token belonging to an admin/employee of the business.

List the human (employee/admin) users who are members of a business. Returns an array of BusinessUser objects with cursor-based pagination (paging.cursors, next/previous), plus summary.total_count when you request summary="total_count". Use this for business-level membership (who belongs to the Business Manager); use List Assigned Users on a specific ad account for per-asset task permissions instead. Can fail with error 415 if the business requires two-factor authentication the caller hasn't completed, or error 200 if the token lacks visibility into the business.

List ad accounts directly owned by a business, as opposed to accounts merely shared with it as a client. Returns an array of ad account objects with cursor-based pagination (paging.cursors, next/previous), plus summary.total_count when you request summary="total_count". Use this to inventory a business's own ad accounts; pass search_query to filter by name or ID, or use List Assigned Users afterward to see who has access to a given account. Distinct from a business's client ad accounts (accounts shared with it, not owned by it), which this tool does not return.

List Facebook Pages directly owned by a business, as opposed to Pages merely shared with it as a client. Returns an array of Page objects with cursor-based pagination (paging.cursors, next/previous), plus summary.total_count when you request summary="total_count". Use this to inventory a business's own Pages; there's no dedicated filter param here, so pull the full list and filter client-side if needed. Distinct from a business's client Pages (Pages shared with it, not owned by it), which this tool does not return.

List the system (bot/API-only) users that belong to a business. Returns an array of SystemUser objects with cursor-based pagination (paging.cursors, next/previous), plus summary.total_count when you request summary="total_count". Use this to audit which API-only users exist on a business; the returned role field only reflects base roles (Admin/Employee), so check List Assigned Users on a specific ad account or Page to see what a system user can actually do there. Requires business_management permission.

Retrieve a single Meta Ads campaign by ID with the exact fields you request (e.g. name, objective, status, effective_status, daily_budget, lifetime_budget, bid_strategy, special_ad_categories). Returns one Campaign object containing only the fields listed in the fields parameter; if fields is omitted, Meta returns just id and name. Use this to fetch one campaign's current values by ID; use List Campaigns to browse or filter campaigns across an account instead. date_preset and time_range only control the aggregation window for any embedded insights-style fields you request -- they do not filter or change core campaign attributes like status, objective, or budget, and start_time/stop_time on the campaign are read-only reflections of its child ad sets' schedules.

Fetch performance insights -- impressions, clicks, spend, actions, and more -- for a single Meta Ads campaign over a date range or breakdown, synchronously. Returns a data array of insight rows for the requested fields plus a paging.cursors object for pagination. Use this for smaller, ad-hoc reporting pulls on one campaign; pass level to force ad- or ad-set-level rows instead of the default campaign-level aggregation. For wide date ranges or many breakdowns that risk timing out or getting rate-limited, use the asynchronous insights report-run workflow instead of this synchronous call. Requires ads_read (or ads_management) permission; insights data is subject to Meta's attribution windows and may be updated retroactively for a few days after the fact.

List campaigns under a Meta Ads ad account, optionally filtered by effective status, completion state, or date range. Returns an array of campaign objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous) and, by default, a summary.total_count. Use this to browse or audit campaigns in bulk; pass an effective_status, is_completed, or date filter to scope large accounts.

Fetch a single custom conversion by ID, including its matching rule and event type. Returns the requested fields, such as name, custom_event_type, rule (or advanced_rule), action_source_type, default_conversion_value, description, pixel, retention_days, and first/last_fired_time. Use this to inspect one known custom conversion, e.g. after finding its id via metaads_custom_conversion_list. Requires ads_management or ads_read permission on the ad account.

Retrieve aggregated firing statistics for a custom conversion over a time window. Returns {data: [CustomConversionStatsResult...], paging}, broken down according to aggregation -- fire counts, device type, host, URL, unmatched counts, or USD amounts. Use this to monitor a custom conversion's volume and matched/unmatched split; use metaads_custom_conversion_get to inspect its configuration (rule, event type) instead. Requires ads_management or ads_read permission on the ad account.

List the custom conversions defined on an ad account. Returns an array of custom conversion objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous). Use this to browse or audit an account's custom conversions before referencing one by id elsewhere (e.g. in ad set optimization); use metaads_custom_conversion_get instead when you already know the id. An ad account can hold at most 100 custom conversions in total. Requires ads_management or ads_read permission on the ad account.

Retrieve details and status of a single Custom Audience or Lookalike Audience by id. Returns the requested fields, e.g. name, subtype, approximate_count (with lower/upper bounds), operation_status, delivery_status, effective_status, issues_info, rule, lookalike_spec, lookalike_audience_ids, sharing_status, and time_created/time_updated. Use this after metaads_customaudience_create to poll operation_status and delivery_status before referencing the audience in a campaign, or to inspect one result from metaads_customaudience_list in full detail. operation_status code 441/442 means the audience is still populating (up to 24h, or up to 6h for lookalikes); code 471 means it was flagged for a policy violation (as of 2025-09-02) and cannot be used in new campaigns.

List Custom Audiences and Lookalike Audiences belonging to an ad account, with optional field selection and filtering. Returns an array of audience objects (id only unless you request more fields) plus cursor-based pagination info (paging.cursors). Use this to browse an account's audiences or find a custom_audience_id for use with metaads_customaudience_get or in ad set targeting; pass fields to also get name, subtype, approximate_count, operation_status, or delivery_status, and filtering to narrow by name or other properties. Requires the ad account to have accepted Meta's Custom Audience Terms of Service; max 500 custom audiences per ad account.

List the ad accounts a Custom Audience is currently shared with, and each one's permission level. Returns data: an array of CustomAudienceAdAccount objects (shared ad account id plus its permission level) with paging info. Use this to audit sharing_status before deciding to unshare, or to confirm metaads_customaudience_share took effect; omit permissions to see all shared accounts regardless of level. Requires access to the ad account that owns the Custom Audience.

Retrieve a single lead's submitted data by lead ID. Returns one Lead object with id, created_time, ad_id, form_id, field_data (an array of question/answer pairs), and optionally is_organic and custom_disclaimer_responses (checkbox_key/is_checked pairs). Use this when you already have one lead's ID -- typically the leadgen_id delivered by a real-time lead webhook payload; use List Form Leads instead to bulk-read all leads for a form. Requires leads_retrieval plus pages_manage_ads (in addition to ads_management, pages_read_engagement, pages_show_list) for full PII access. Subject to the same per-Page rate limit as List Form Leads (200 x 24 x leads created on that Page in the last 90 days).

Retrieve a single Meta Ads lead generation form by ID with the exact fields you request (e.g. name, status, questions, leads_count, created_time, expired_leads_count). Returns one Leadgen Form object containing only the fields listed in the fields parameter; if fields is omitted, Meta returns just id and name. Use this to inspect one form's questions or status before pulling its submissions with List Form Leads; use List Leadgen Forms to browse a Page's forms instead of fetching one by ID. Requires a Page access token with pages_read_engagement (or pages_show_list) at minimum; ads_management, pages_manage_ads, and leads_retrieval unlock additional fields.

List the lead generation forms that have been created for a given Facebook Page. Returns an array of leadgen form objects with the requested fields plus cursor-based pagination info. Use this to find a Page's form ids (and names/status) before reading leads from a specific form or checking a form's questions. Requires a Page access token with pages_show_list and pages_read_engagement at minimum; ads_management, pages_manage_ads, and leads_retrieval give access to more fields.

List the leads that have been submitted to a specific Meta Ads lead generation form. Returns an array of Lead objects (id, created_time, ad_id, form_id, field_data question/answer pairs, plus optionally is_organic and custom_disclaimer_responses) plus cursor-based pagination info. Use this to bulk-read all of a form's leads or a date-bounded slice of them; use Get Lead instead when you already have one lead's ID, typically from a real-time lead webhook payload. Requires leads_retrieval plus pages_manage_ads (in addition to ads_management, pages_read_engagement, pages_show_list) for full field access -- without leads_retrieval some PII fields may be withheld. Subject to a per-Page rate limit of 200 x 24 x the number of leads created on that Page in the last 90 days.

Get a single Commerce Merchant Settings (CMS) object by ID -- a Business's Commerce/shop onboarding and configuration. Returns the requested fields (e.g. id, display_name, merchant_page_id, and other configuration fields Meta exposes on this node); without an explicit fields list, only minimal defaults come back. Use this to inspect one known CMS_ID's configuration, e.g. after finding it via metaads_merchant_settings_list -- pass that same cms_id on to metaads_order_list and other order-management tools. Requires a Page or Business access token with commerce permissions on the Business that owns the shop.

List the Commerce Merchant Settings (CMS) objects associated with a Business -- how you discover the CMS_ID needed for every order/shipment/cancellation/refund call against that Business's shop. Returns an array of CommerceMerchantSettings objects with cursor-based pagination info (paging.cursors, next/previous); each object's id is the CMS_ID. Use this once per Business to find its CMS_ID, then pass that id as cms_id to metaads_order_list and related order-management tools. Requires a Page or Business access token with commerce permissions on the Business that owns the shop.

Retrieve a single offline event set (dataset)'s fields by ID, such as its name and availability, before uploading events to it. Returns the requested fields on the underlying dataset object (the same AdsPixel-shaped object Meta also uses for web pixels) -- e.g. name, is_unavailable, data_use_setting, creation_time, last_fired_time, event_time_min, event_time_max; if fields is omitted, Meta returns only a minimal default (typically id). Use this to validate a dataset_id and confirm it isn't unavailable/disabled before calling metaads_offline_event_set_upload_events, or to check its data_use_setting; use metaads_offline_event_set_list_uploads instead to see upload history, and metaads_adspixel_get if you already know the ID belongs to a web pixel rather than an offline dataset (both call the same underlying object). Requires ads_management or ads_read permission and access to the business or ad account that owns the dataset.

List the history of offline event upload batches for an offline event set (dataset), for monitoring recent uploads. Returns an array of upload-batch objects (fields such as id, upload_tag, first_upload_time, last_upload_time, api_calls, event_time_min, event_time_max, and match/validity stats depend on the fields you request) plus cursor-based pagination info (paging.cursors, next/previous). Use this as a lightweight verification step after metaads_offline_event_set_upload_events to confirm a batch (matched by upload_tag) was received and processed; use metaads_offline_event_set_get instead to check the dataset's own metadata rather than its upload history. Read-only edge -- there is no create/update/delete here, only reading upload history.

Get a single Commerce order's details by order ID, including buyer, shipping, and payment fields when explicitly requested. Returns one order object with id, order_status, created, and last_updated by default; pass fields to also get items, buyer_details, channel, merchant_order_id, ship_by_date, shipping_address, selected_shipping_option, or estimated_payment_details. Use this to inspect one specific order (e.g. after finding its id via List Orders, or from a webhook/notification); use List Orders to browse or filter multiple orders instead. Requires a Page Access Token for the Page/Business tied to the order's CMS_ID, with EDITOR role or higher on that Page.

List the line items -- products, quantities, and prices -- belonging to a specific Commerce order. Returns an array of item objects (id, product_id, retailer_id, quantity, price_per_unit by default; pass fields for product_name, selected_shipping_option, status, tax_details, or customization) plus cursor-based pagination. Use this before building a shipment, cancellation, or refund request, since those reference items by retailer_id or item_id -- find the order_id first via metaads_order_list or metaads_order_get. Requires a Page Access Token for the Page/Business tied to the order's CMS_ID, with EDITOR role or higher on that Page.

List Commerce orders under a Commerce Merchant Settings (CMS) account, filtered by order state, last-updated time window, or shipment/cancellation/refund status. Returns an array of order objects (id, order_status, created, last_updated by default -- pass fields for more) with cursor-based pagination (default page size 25, via before/after cursors). Use this to find orders needing action (e.g. state=["CREATED"] for orders awaiting acknowledgement) before acting on them individually with Get Order or Acknowledge Order; omitting state returns only CREATED orders by default. Requires a Page Access Token for the Page/Business tied to the CMS_ID, with EDITOR role or higher on that Page -- find the CMS_ID first with metaads_merchant_settings_list.

List refunds already issued against a Commerce order. Returns an array of refund objects (id, refunded items with retailer_id/product_id/refund_subtotal, refund_reason, and refund_amount with subtotal/tax/shipping/total) plus cursor-based pagination. Use this to check refund history and amounts already issued before calling metaads_order_refund for another partial refund on the same order. Requires a Page Access Token for the Page/Business tied to the order's CMS_ID, with EDITOR role or higher on that Page.

List the shipments already recorded against a Commerce order, including their tracking info and shipped items. Returns an array of shipment objects (id, external_shipment_id, items with per-item tax detail, and tracking_info with carrier/tracking_number) plus cursor-based pagination. Use this to check existing shipments before calling metaads_order_shipment_create for the remaining unfulfilled items, or before issuing a refund tied to a specific shipment. Requires a Page Access Token for the Page/Business tied to the order's CMS_ID, with EDITOR role or higher on that Page.

List the business and system users assigned to a Page owned by a business, with their granted and permitted tasks. Returns an array of AssignedUser objects, each with tasks (currently granted, from a Page-specific set including MANAGE, CREATE_CONTENT, MODERATE, MESSAGING, ADVERTISE, ANALYZE, and other specialized roles) and permitted_tasks (what's assignable), plus paging and, when requested, summary.total_count. Use this to audit who can manage a specific Page; use List Business Users or List System Users first if you need to resolve a user's name from its ID. This tasks enum is Page-specific and differs from the ad-account/catalog task set (MANAGE, ADVERTISE, ANALYZE, DRAFT, AA_ANALYZE). Requires a business ID scoping the lookup, a Page access token with the MANAGE task, and typically the pages_manage_metadata permission (some apps additionally need the Page Public Content Access feature to avoid rate limits).

Retrieve fields and metadata for a single product feed, including its fetch schedule, latest upload summary, and product count. Returns one ProductFeed object containing only the fields listed in fields; schedule, update_schedule, and latest_upload come back as nested objects. If fields is omitted, Meta returns just id and name. Use this to check a feed's configuration or most recent ingestion result by ID; use List Product Feeds to browse or discover feed IDs under a catalog first. Requires catalog_management access on the catalog that owns this feed.

List the product feeds belonging to a Meta product catalog. Returns an array of ProductFeed objects with the requested fields plus cursor-based pagination info (paging.cursors, next/previous). Use this to find a feed's ID before reading its schedule/upload history with Get Product Feed, or before listing its upload sessions. Requires the caller's business to be registered in Business Manager and to have catalog_management access on the catalog (as an owner or an assigned agency).

List the attribute-transformation rules configured on a product feed for scheduled catalog ingestion. Returns an array of ProductFeedRule objects plus cursor-based pagination (paging.cursors, next/previous); there are no documented filter parameters, so every rule on the feed is returned a page at a time. Use this to audit or debug how a feed's incoming rows get transformed (e.g. renamed or computed fields) before they're ingested; set rules on Create Product Feed to add new ones. Requires catalog_management access on the catalog that owns this feed.

Retrieve status, item counts, and error/warning counts for a single product feed upload session. Returns one ProductFeedUpload object containing only the fields listed in fields -- id, start_time, end_time, filename, url, num_detected_items, num_invalid_items, num_deleted_items, num_persisted_items, error_count, warning_count, input_method (e.g. Manual Upload, Server Fetch, Google Sheets Fetch, Reupload Last File, User initiated server fetch), and error_report (a file handle, populated only after requesting it on the error_report edge). If fields is omitted, Meta returns just id. Use this to poll an upload triggered by metaads_product_feed_upload_trigger, or to inspect one found via metaads_product_feed_upload_list, until end_time is set and the counts settle. Requires catalog_management access on the catalog that owns the feed this upload belongs to.

List recent upload sessions (manual and scheduled) for a product feed. Returns an array of ProductFeedUpload objects (id, start_time, end_time, filename, url, num_detected_items, num_invalid_items, num_deleted_items, num_persisted_items, error_count, warning_count, input_method, error_report) plus cursor-based pagination info. Use this to check whether a scheduled or manual upload succeeded, and how many items it detected/persisted/rejected; pass an upload's id to metaads_product_feed_get-adjacent detail calls (not included in this tool set) to inspect a specific error report further. Requires catalog_management access on the catalog that owns this feed.

Retrieve a single product catalog's fields and settings by ID. Returns the requested ProductCatalog fields (e.g. name, business, vertical, product_count, feed_count, is_catalog_segment, is_local_catalog, default_image_url, fallback_image_url, da_display_settings) as a single object. Use this to inspect or verify one catalog's configuration; use List Product Catalogs to browse all catalogs owned by a business.

List the product catalogs owned directly by a business, for use with Commerce and Dynamic/Catalog ads. Returns an array of ProductCatalog objects with cursor-based pagination (paging.cursors, next/previous), plus summary.total_count when you request summary="total_count". Use this to find a catalog's ID before referencing it (e.g. as product_set_id) in a Custom Audience or a catalog-driven ad. Requires catalog_management (and typically ads_management) permission on the business.

List the business and system users assigned to a product catalog, with their granted and permitted tasks. Returns an array of AssignedUser objects, each with tasks (currently granted, e.g. MANAGE, ADVERTISE, MANAGE_AR, AA_ANALYZE) and permitted_tasks (what's assignable), plus paging and, when requested, summary.total_count. Use this to audit who can manage a specific catalog before granting or changing access with Assign Product Catalog User; use List Business Users or List System Users first if you need to resolve a user's name from its ID. Requires a business ID scoping the lookup, plus ads_management and catalog_management permissions.

List product catalogs owned by other businesses (clients) that have been shared with this business. Returns an array of ProductCatalog objects, each including permitted_roles (the roles this business may assign on that catalog), plus cursor-based pagination (paging.cursors, next/previous) and, when requested, summary.total_count. Use this to find catalogs a client has shared with you; use List Product Catalogs instead for catalogs this business owns directly. This edge is read-only -- creating or removing a catalog share isn't supported here. Requires catalog_management (and typically ads_management) permission on the business.

Retrieve full details of a single product item by its Graph API node ID. Returns the requested Product fields (e.g. id, name, retailer_id, price, currency, availability, condition, brand, inventory, sale_price, gtin, errors) as a single object. Use this to inspect one SKU's current data and any validation errors flagged by Meta; use List Product Items to browse or filter items across a whole catalog.

List product items (SKUs) in a catalog, optionally filtered by approval status or a specific data-quality error type. Returns an array of Product objects with the requested fields plus cursor-based pagination (paging.cursors, next/previous) and, when requested, summary.total_count. Use this to audit catalog inventory or find items flagged with a given error before fixing and re-syncing them; use Get Product Item to fetch one item's full details by ID.

Retrieve a single product set's details -- name, filter rule, product_count, and metadata -- by ID. Returns the requested ProductSet fields as a single object. Use this to inspect a specific set or confirm a create/update took effect; use List Product Sets to browse or search all sets in a catalog.

List the product sets defined in a product catalog, optionally filtered by parent/ancestor set or retailer ID. Returns an array of ProductSet objects with the requested fields plus cursor-based pagination (paging.cursors, next/previous) and, when requested, summary.total_count. Use this to browse or audit a catalog's product sets before referencing one by ID (e.g. in a Custom Audience or ad targeting scope); use Get Product Set for a single set's full details.

List the product items that currently belong to (match the filter of) a specific product set. Returns an array of Product objects with the requested fields plus cursor-based pagination (paging.cursors, next/previous) and, when requested, summary.total_count. Use this to audit or QA which items match a set's filter, scoped to just that one set; use List Product Items instead to list every item in the whole catalog regardless of set membership. Requires catalog_management access on the catalog that owns this product set.

Fetch the paginated result rows produced by a completed asynchronous Ads Insights report run. Returns a data array of insight rows for the fields/breakdowns configured when the report run was created, plus paging.cursors for pagination. Call this only after metaads_report_run_get_status reports async_status 'Job Completed' and async_percent_completion 100 -- querying earlier can return empty or partial data. Results (and the report_run_id itself) are only guaranteed retrievable for 30 days after the run was created; once expired, start a new job with metaads_account_insights_create_report_run.

Check the processing status and completion percentage of an asynchronous Ads Insights report run. Returns the AdReportRun object: async_status (e.g. Job Not Started, Job Started, Job Running, Job Completed, Job Failed, Job Skipped), async_percent_completion (0-100), time_completed, and error_code/error_message when failed. Poll this after metaads_account_insights_create_report_run until async_status is 'Job Completed' and async_percent_completion is 100, then fetch rows with metaads_report_run_get_insights; it works for a report_run_id created at any level (account, campaign, ad set, or ad), so use it regardless of which level started the job. Use sensible polling intervals rather than tight loops -- there is no cancel operation, and the run simply expires 30 days after creation.

Check whether specific targeting options (interest, behavior, demographic, or other targeting-taxonomy IDs you already have) are currently deliverable, deprecating, or blocked from exclusion use. Returns one entry per requested id with current_status (NORMAL, NON-DELIVERABLE, DEPRECATING, NON-DELIVERABLE-IN-EXCLUSION, or UNKNOWN) plus a future_plan map of any upcoming status changes keyed by timestamp. Use this to audit targeting option IDs already saved in a targeting_spec before reusing it (e.g. an old flexible_spec whose interest/behavior ids may have gone stale); use Search Targeting Options instead when starting from a free-text keyword, or Validate Interest Targeting to check/expand interests specifically by name. Get the option ids to check from Search Targeting Options, Validate Interest Targeting, or an existing targeting_spec's flexible_spec.

Autocomplete-search Meta's targeting taxonomy -- interests, behaviors, demographics, life events, industries, locales, employers, job titles, and schools/majors -- by keyword, or browse a whole category class without a keyword. Returns an array of matching options; the fields present (id/name/path/audience_size vs coverage/subtext) depend on which type you requested. Use this to look up interest/behavior/demographic ids and audience sizes for building a targeting_spec's flexible_spec (e.g. for Create Ad Set or Get Delivery Estimate); use Search Locations for geographic targeting instead.

Search or validate geographic targeting locations (countries, regions, cities, zips, electoral districts), bulk-fetch metadata for known location keys, or get a suggested radius size for radius-based targeting around a point. Returns an array of location objects (for adgeolocation/adgeolocationmeta, fields like key, name, type, supports_city/supports_region, country_codes) or, for adradiussuggestion, a suggested_radius and distance_unit. Use this to build the geo_locations block of a targeting_spec (e.g. for Create Ad Set or Get Delivery Estimate); use Search Targeting Options for interests/behaviors/demographics instead.

Validate a list of known interest IDs or names as still targetable (type=adinterestvalid), or get related interest suggestions to expand an audience from a set of existing interests (type=adinterestsuggestion). For adinterestvalid, returns one entry per input interest with a valid boolean plus id and audience_size when it's still valid. For adinterestsuggestion, returns an array of related interests with id, name, audience_size, path (category hierarchy), and description. Use this when you already have a batch of known interest IDs/names to check or expand -- e.g. before saving a targeting_spec someone else authored, or to grow reach on an existing flexible_spec. Use metaads_targeting_search instead when starting from a free-text keyword rather than known interests. Commonly chained after metaads_targeting_search when building or auditing an ad set's flexible_spec.

Start an asynchronous Ads Insights report job for an ad account, using the same field/level/breakdown/date parameters as a synchronous insights request. Returns {report_run_id: "<id>"} immediately; the job continues running server-side after this call returns. Use this instead of metaads_account_insights_get for large or high-cardinality pulls (many breakdowns, long date ranges, reach breakdowns on data older than 13 months) that risk timing out or being truncated synchronously; poll metaads_report_run_get_status with the returned report_run_id, then fetch rows with metaads_report_run_get_insights once it reports Job Completed. report_run_id expires 30 days after creation -- do not store it for long-term use; reach-breakdown async requests on data older than 13 months are capped at 10 per ad account per day.

Duplicate an existing Meta Ads ad, optionally into a different ad set and with a renamed or modified creative. Returns copied_ad_id, the new ad's id. Use this to quickly clone a working ad instead of rebuilding it with metaads_ad_create; pair with rename_options to keep names organized when duplicating in bulk, or with creative_parameters to tweak copy/creative on the new ad without touching the original. Requires ads_management permission on the source ad.

Create a new Meta Ads ad under an ad account, attaching it to an ad set and a creative. Returns {id, success} for the newly created ad. Use this after Create Ad Set and after an ad creative already exists (built separately, e.g. via Ads Manager or an AdCreative call) -- pass that creative's ID via the creative parameter. New ads enter PENDING_REVIEW and won't deliver until Meta approves them, regardless of the status you set. The request body is sent as ordinary JSON (all fields, including the nested creative object, are plain JSON values) -- this is not a multipart/file upload.

Start an asynchronous Ads Insights report job for a single ad, using the same fields/breakdowns/filtering/date parameters as a synchronous insights request. Returns {report_run_id: "<id>"} immediately; the job continues running server-side after this call returns. Use this instead of metaads_ad_get_insights for larger or more complex queries (wide date ranges, high-cardinality breakdowns) that risk timing out or getting rate-limited synchronously; poll metaads_report_run_get_status with the returned report_run_id until async_status is 'Job Completed', then fetch rows with metaads_report_run_get_insights. Prefer date_preset over a custom time_range, and avoid combining many breakdowns at broad scope to reduce throttling (reported via the x-fb-ads-insights-throttle response header). Requires ads_read permission. report_run_id expires 30 days after creation -- do not store it for long-term use.

Update an existing ad's name, status, creative, or other mutable fields. Returns the updated ad's id on success. Use this to pause, resume, rename, archive, or delete an ad, or attach a different existing ad creative to it; it cannot move the ad to a new ad set. Requires ads_management permission; archived ads only accept name changes and status→DELETED, and deleted ads only accept name changes.

Assign or update a business or system user's task-based permissions on a Meta Ads ad account. Returns {success: true} -- not the updated resource, so re-fetch with metaads_adaccount_list_users to confirm the new task set. Use this to grant or change access with Meta's task-based model (MANAGE, ADVERTISE, ANALYZE, DRAFT, AA_ANALYZE) instead of legacy account roles; calling it again for the same user replaces their entire task set, it does not merge with what they already had. Requires the caller to already have rights to grant the requested tasks on this ad account; error 2620 means the call itself is invalid for that purpose.

Create a new ad account under a Business Manager business. Returns the new account's id/account_id plus business_id, end_advertiser_id, media_agency_id, and partner_id. Use this only when you need to provision a brand-new ad account programmatically; most workflows create ad accounts through the Business Manager or Ads Manager UI instead, and this endpoint typically requires an elevated Marketing API access tier plus business verification. Use metaads_adaccount_list_owned_by_business afterward to confirm the new account shows up. Requires business_management permission and admin rights on the business. end_advertiser, media_agency, and partner each become immutable once set to a value other than 'NONE'. Common errors: 3979 (business exceeded its max ad accounts), 3980/3902 (account in review or technical creation failure).

Update an ad account's name, spend cap, notification preference, DSA payor/beneficiary, or its reseller/agency declarations (end_advertiser, media_agency, partner, agency_client_declaration). Returns {success: true} on completion; fetch the account afterward with metaads_adaccount_get to confirm the new values. Use this to rename an account, raise or remove its spend cap, toggle notifications, or record a required regulatory declaration -- set default_dsa_payor and default_dsa_beneficiary together (both or neither), since a partial update to just one is rejected. end_advertiser, media_agency, and partner each require a real numeric Page/App ID on update (Meta rejects a 'NONE'/'UNFOUND' sentinel here, unlike at account creation) and become permanently locked once set, so a second update call on an already-set field will fail; agency_client_declaration additionally requires Business Manager Admin privileges on the account.

Create a new ad creative in an ad account's library from an image/video reference or an inline unpublished page post. Returns the new creative's id (or, if the submission is a byte-for-byte duplicate of an existing creative, that existing creative's id). Upload the image or video first with metaads_adimage_create / metaads_advideo_create so you can reference it here by hash or id; provide exactly one of object_story_spec, object_story_id, or a simple image/video + link_url combination. Requires ads_management permission; political or social-issue ads must also set authorization_category.

Update an existing ad creative's name, status, or ad labels -- the only fields Meta lets you change once a creative is created. Returns {success: true}, plus an echo of any fields you request via the fields parameter (Graph API's read-after-write behavior). Use this to rename a creative, move it between ACTIVE and DELETED, or retag its labels; to change actual creative content (image, video, copy, object_story_spec) create a new creative with metaads_adcreative_create instead. Requires ads_management permission and admin access to both the app and the ad account.

Upload a new image into an ad account's library from base64-encoded bytes, or copy an existing image from another ad account without re-uploading it. Returns a map keyed by the filename you supplied, containing that image's hash, url, url_128, url_256, height, and width. Use the returned hash to reference this image from metaads_adcreative_create; use copy_from instead of bytes/filename when you already have read access to the image in another ad account. Provide exactly one of bytes+filename or copy_from. Requires ads_management on the target ad account, and read access to source_account_id when using copy_from. There is no update operation — re-upload to change an image.

Create a new automated rule on an ad account that evaluates campaigns, ad sets, or ads on a schedule or trigger and takes an action (pause, notify, change budget/bid, etc.) when its filters match. Returns {id} for the new ad rule. Use this to automate routine account management, e.g. pausing underperforming ads or notifying on a budget change; use Update Ad Rule afterward to enable/disable it or adjust its conditions. Trigger-based rules only support NOTIFICATION, PAUSE, UNPAUSE, or PING_ENDPOINT execution types; schedule-based rules support all execution types except PING_ENDPOINT.

Update an existing automated rule's name, status, evaluation_spec, execution_spec, or schedule_spec. Returns {success: true} on completion; fetch the rule afterward with Get Ad Rule to confirm the new values. Use this to pause or resume a rule's automatic evaluation (set status to DISABLED/ENABLED -- there is no separate enable/disable endpoint), or to change its conditions/action without recreating it; use Create Ad Rule to make a new one instead. Only the fields you provide are changed; leave the rest blank to keep their current values.

Duplicate an existing Meta Ads ad set, optionally deep-copying its child ads, into the same campaign or a different one. Returns {copied_adset_id, ad_object_ids} where ad_object_ids lists each copied child object's ad_object_type, source_id, and copied_id. Use this to clone an existing ad set as a starting point instead of building one from scratch with Create Ad Set; use metaads_campaign_copy instead to duplicate a whole campaign (optionally with its ad sets and ads). deep_copy is capped at 3 child ads for a synchronous call (51 for asynchronous), so prefer manual ad creation for larger structures. Requires ads_management permission on the source ad set; the copy is created PAUSED unless status_option says otherwise. Counts against the destination campaign's ad-set-per-account limits (5,000 for standard accounts, 10,000 for bulk accounts).

Create a new Meta Ads ad set under an ad account, attaching it to a campaign with targeting, a budget/schedule, an optimization goal, and (for most objectives) a promoted object. Returns {id, success} for the newly created ad set, which you then use with Create Ad to attach ads. Use this to build out a campaign's structure; use Update Ad Set to change an existing one afterward. New ad sets default to PAUSED status unless status is set to ACTIVE, and won't deliver until their parent campaign is also ACTIVE.

Update an existing Meta Ads ad set's name, status, budget, schedule, targeting, or bid settings. Returns {success: true} on completion; fetch the ad set afterward with Get Ad Set to confirm the new values. Use this to pause/resume an ad set, adjust its budget, or retarget it -- use Create Ad Set to make a new one instead. status can also be set to ARCHIVED or DELETED here (soft-removal states not available at creation), and some fields (e.g. the custom conversion behind an existing promoted_object) become immutable once the ad set has delivery history, which Meta rejects with a 400 error.

Create a new Meta Pixel under an ad account. Returns {id} for the newly created pixel. Use metaads_adspixel_list first to check whether the account already has a pixel -- Meta restricts most ad accounts to a single pixel, so this call commonly fails with error code 6200 ("a pixel already exists for this account") or 6202 ("more than one pixel exists") when one is already present; use metaads_adspixel_update on the existing pixel instead of retrying create. Requires ads_management permission on the ad account.

Send one or more server-side conversion events for a pixel via the Conversions API. Returns Meta's events_received count, fbtrace_id, and (when test_event_code is set) a messages array describing how the Test Events tool processed each event. Use this to report events (Purchase, Lead, ViewContent, etc.) directly from your server, deduplicated against browser Pixel events via a shared event_id -- pass test_event_code only while validating in Events Manager's Test Events tab, and omit it in production. Requires an access token with ads_management (or a system-user token) tied to the pixel; all user_data identity fields except client_ip_address, client_user_agent, fbc, fbp, subscription_id, fb_login_id, and anon_id must already be SHA-256 hashed (lowercased and trimmed) before being sent.

Update a Meta Pixel's settings such as its name, automatic matching configuration, and data-use restrictions. Returns {"success": true} on success. Use this to rename an existing pixel, toggle automatic (advanced) matching and which fields it uses, or change data_use_setting / first_party_cookie_status / server_events_business_ids -- since most ad accounts are limited to one pixel, this is the usual way to change pixel behavior instead of creating a new one via metaads_adspixel_create. Requires ads_management permission on the ad account or business that owns the pixel.

• Idempotent

Upload a new video into an ad account's library from a hosted file URL, or reuse an existing Instagram video. Returns the new video's id. Use file_url for a video already reachable at a public URL; use source_instagram_media_id to reuse an Instagram video instead of re-uploading. Reference the returned id from metaads_adcreative_create's video-based creatives. Requires ads_management permission (and instagram_basic when pulling from an Instagram media id). Provide exactly one of file_url or source_instagram_media_id.

Create a new system (bot) user within a business for programmatic, token-based API access. Returns {id: "<SYSTEM_USER_ID>"} for the new system user -- not a full SystemUser object, so re-fetch with List System Users to see its role and other fields. Use this before granting a bot access to any ad account, Page, or catalog; creating the system user alone does not grant it any asset access -- follow up with an assign-user tool (e.g. Assign Ad Account User) on each target asset. Requires business_management permission and admin-level access on the business; the calling app must also be part of that business.

Duplicate a Meta Ads campaign, optionally deep-copying its child ad sets and ads, with field overrides and rename rules applied to the copy. Returns {copied_campaign_id, ad_object_ids} where ad_object_ids lists each copied object's ad_object_type, source_id, and copied_id. Use this to clone an existing campaign as a starting point instead of building one from scratch with Create Campaign. deep_copy is capped at 3 child objects for a synchronous call (51 for asynchronous), so prefer manual Create Ad Set / Create Ad calls for larger structures. Requires ads_management permission on the source campaign; the copy is created PAUSED unless status_option says otherwise.

Create a new Meta Ads campaign under an ad account with an objective, a special ad category declaration, and optional budget or bid strategy settings. Returns {id, success} for the newly created campaign, which you then use with Create Ad Set to build out its structure. Use this to start a brand-new campaign; use Update Campaign to change an existing one's settings afterward. New campaigns default to PAUSED status unless status is set to ACTIVE, and set either daily_budget or lifetime_budget here only if you intend to manage budget at the campaign level (Campaign Budget Optimization) rather than per ad set.

Update an existing Meta Ads campaign's name, status, budget, bid strategy, schedule, or objective. Returns {success: true} on completion; fetch the campaign afterward with Get Campaign to confirm the new values. Use this to pause/resume a campaign, adjust its Campaign Budget Optimization budget, or change its schedule -- use Create Campaign to make a new one instead. Set daily_budget or lifetime_budget here only if the campaign already manages budget at the campaign level; switching a campaign between campaign-level and ad-set-level budgeting while child ad sets already have their own budgets set can fail, and campaigns with 70+ CBO-optimized ad sets cannot change bid_strategy or disable CBO.

Create a new custom conversion on an ad account from a pixel or dataset event, optionally filtered by a rule and categorized by a conversion event type. Returns {id} identifying the new custom conversion (plus is_custom_event_type_predicted). Use this once to define a trackable conversion -- e.g. visits matching a URL pattern, or a specific pixel/dataset event -- before referencing its id in ad set optimization, campaign reporting, or conversion-based audiences. Ad accounts are capped at 100 custom conversions.

Update an existing custom conversion's name, description, or default conversion value. Returns {"success": true} on success. Use this to rename a custom conversion, change its Events Manager description, or adjust its default value -- the matching rule and event type can't be changed after creation, so create a new custom conversion (metaads_custom_conversion_create) instead if those need to differ. Fails if the conversion has been flagged by Meta for policy reasons; such conversions can't be modified.

• Idempotent

Add or update members of a Custom Audience by uploading hashed user identifiers (email, phone, external ID, mobile advertiser ID, etc.), up to 10,000 records per call. Returns num_received, num_invalid_entries, and invalid_entry_samples; membership changes apply asynchronously and can take up to about 24 hours to show up in targeting. Use this to grow or refresh a customer-list Custom Audience; use Create Lookalike Audience afterward to model new users from the audience you build here. Values other than the pre-hashed *_SHA256 schema keys must already be normalized (lowercased/trimmed) and SHA256-hashed client-side before calling this tool -- the caller must be an admin of both the app and the ad account.

Create a new Custom Audience under an ad account -- a blank or customer-file audience, a website/app/engagement rule-based remarketing audience, or a catalog-driven value-based audience. Returns {id: "<CUSTOM_AUDIENCE_ID>"} for the new audience (or an existing audience's id if this exact submission duplicates one already created with enable_fetch_or_create). The audience starts blank -- for a customer-file audience, add members afterward via the Custom Audience's /users edge; poll it with metaads_customaudience_get (operation_status, delivery_status) before referencing it in campaign targeting. Most audiences only need name and subtype: CUSTOM (a plain or customer-file audience, optionally combined with rule for website/app/video remarketing). A few UI-only subtypes (e.g. IG_BUSINESS_EVENTS, FB_EVENT_SIGNALS, MULTI_DATA_EVENTS) cannot be created through this API. Max 500 custom audiences per ad account.

Create a Lookalike Audience modeled on a seed Custom Audience, a Facebook Page's fans, or people who converted through specific campaigns or ad sets. Returns the new audience's id; the lookalike takes 1-6 hours to fully populate before it's ready to target with ads (poll it separately to confirm). Use this instead of a plain Custom Audience when you want Meta to algorithmically find similar users at scale from a seed source; use Update Custom Audience afterward to rename or retarget it. Requires exactly one seed: origin_audience_id (an existing Custom Audience with 100+ members), page_id (a page-fan lookalike), or origin_ids with conversion_type=campaign_conversions (100+ unique conversions, 200+ recommended).

Share a Custom Audience with one or more other ad accounts inside the same Meta Business, so they can use it for targeting. Returns {success: true} on completion. Use this to let a sibling ad account in the same Business Manager target this audience without duplicating it; the recipient account can use the audience for targeting but cannot modify it or use it as a lookalike seed. Use metaads_customaudience_list_shared_accounts afterward to audit sharing_status. Both the owning and recipient ad accounts must be claimed by the same Meta Business (Business Manager), or the share is rejected.

Update an existing Custom Audience's metadata or targeting rule -- name, description, retention window, opt-out link, allowed domains, or remarketing rule. Returns {success: true} on completion; the audience's subtype (e.g. LOOKALIKE, WEBSITE, CUSTOM) can never be changed after creation. Use this to adjust an audience you already created; use Create Lookalike Audience or Add Users to Custom Audience to build a new one instead. Fails with an integrity-restriction error (1713231) if the audience is flagged and the update doesn't remove the violating fields; flagged lookalike/DFCA audiences (1713228) can't be edited at all.

• Idempotent