PaidSync

COPY one Google Ads ad group into another EXISTING campaign of the same account, the way to move an ad group (Google cannot change an ad group's campaign). Builds exactly the plan plan_ad_group_copy shows (dry_run=true, the default, returns that plan and sends nothing). Live: Google first validates the exact operations (validate_only) and the copy stops on any error; then ONE all-or-nothing mutate creates the ad group PAUSED with its keywords, negatives, audiences, demographics, AI Max controls (locations of interest, brand lists, URL inclusions), ads (RSA pins kept), asset and asset set links (same assets), customizer values and bid modifiers, plus the label paidsync_copy_of_<source id> that marks it as this source's copy; then the copy is read back and every copied item is compared byte-for-byte, URLs included, and every difference is listed as a defect. Returns the exact old-to-new id map. One copy per source per campaign: a second call returns the existing copy when it matches, and refuses when it does not, whatever the name. Never changes the destination campaign, its shared sets, or the source. Not retried automatically.

copy_ad_group

Mark an event as a conversion (key event) in GA4. The event must already be firing in your data stream (e.g. via GTM).

create_ga4_conversion_event

Create a tag in a GTM workspace. Common types: 'googtag' (Google Tag/GA4 config), 'gaawe' (GA4 Event), 'awct' (Google Ads Conversion), 'gclidw' (Conversion Linker), 'html' (Custom HTML), 'img' (Custom Image). Use firing_trigger_id to attach a trigger. Pass either workspace_path OR (account_id + container_id + workspace_id).

create_gtm_tag

Create a trigger in a GTM workspace. Common types: 'pageview' (All Pages), 'domReady' (DOM Ready), 'windowLoaded' (Window Loaded), 'click' (All Clicks), 'linkClick' (Just Links), 'formSubmission' (Form Submission), 'customEvent' (Custom Event), 'timer', 'scrollDepth'. Pass either workspace_path OR (account_id + container_id + workspace_id).

create_gtm_trigger

Create a user-defined variable. Common types: 'v' (Data Layer Variable), 'jsm' (Custom JavaScript), 'c' (Constant), 'gas' (Google Analytics Settings), 'remm' (Regex Table), 'smm' (Lookup Table). Pass either workspace_path OR (account_id + container_id + workspace_id).

create_gtm_variable

Create a version from a workspace (snapshot of all changes). This prepares the changes for publishing but does NOT publish them yet. Pass either workspace_path OR (account_id + container_id + workspace_id).

create_gtm_version

Create a new workspace in a GTM container. Best practice: create a workspace for your changes instead of editing the Default Workspace directly. Pass either container_path OR (account_id + container_id).

create_gtm_workspace

Create a Facebook Ad end-to-end. Supports single image, single video, and carousel formats. Validates assets and page access before creating. Provide page_id + image_url + link + message to build the creative automatically, or pass an existing creative_id. For video ads, use ad_format='single_video' + video_id (a video already in the account; nothing is re-uploaded) or video_url; the thumbnail is picked automatically. For carousel ads, use ad_format='carousel' + carousel_cards. For Stories/Reels, also provide story_image_url (9:16). For Instagram placements, provide instagram_user_id (auto-detected from the page when omitted). Use dry_run=true (default) to run pre-publish checks without creating. TIP: Use list_fb_pages to find your page_id.

create_fb_ad

Create a Facebook Ad Set with audience targeting. Use dry_run=true (default) to preview. OBJECTIVE/GOAL COMBOS: OUTCOME_SALES + OFFSITE_CONVERSIONS + pixel_id + PURCHASE event (most reliable). OUTCOME_LEADS + LEAD_GENERATION + page_id (for lead forms). OUTCOME_TRAFFIC + LINK_CLICKS or LANDING_PAGE_VIEWS. OUTCOME_AWARENESS + REACH or IMPRESSIONS. OUTCOME_ENGAGEMENT + POST_ENGAGEMENT. NOTE: OUTCOME_LEADS may not work with all optimization_goals on all accounts. If you pass parent_objective the tool will VALIDATE the optimization_goal against it and throw on mismatch (e.g. OUTCOME_SALES + REACH is rejected). PLACEMENTS: Always ask the user. 'all' (Advantage+ auto), 'facebook_only', 'instagram_only', 'facebook_and_instagram'. ADVANTAGE+ AUDIENCE: When enabled (default on create), age_max must be 65; a lower age_max is raised to 65 and the preview shows the raised value. EU TARGETING: an ad set reaching the EU (city/region/zip keys in EU countries count) needs a beneficiary and a payer: pass dsa_beneficiary and dsa_payor, or none if the ad account has saved EU defaults; the preview says which applies and asks only when Meta would refuse. CBO WARNING: If campaign uses CBO, do NOT set daily_budget or lifetime_budget. AUDIENCES: target or exclude custom/lookalike audiences via custom_audience_ids / excluded_custom_audience_ids (list_fb_audiences); every id is checked against the ad account before the preview, max 500 per list. GEO: countries and/or country_groups (e.g. ['gcc']), plus cities/region_keys/zip_keys resolved with search_fb_locations; no geo at all defaults to US and the response echoes the applied targeting. LOCATION EXCLUSIONS: excluded_countries, excluded_region_keys, excluded_cities, excluded_zip_keys (GCC without Qatar: country_groups ['gcc'] + excluded_countries ['QA']); sent as Meta excluded_geo_locations and echoed in the preview and result. DETAILED EXCLUSIONS ARE REFUSED: Meta removed interest/behavior/demographic exclusions from ad sets (Marketing API v22.0, all versions from 21 April 2025), so excluded_interests / excluded_behaviors / excluded_demographics return an error; exclude a custom audience instead, or exclude employers account-wide (update_fb_account_controls, or Meta Ads Manager > Advertising settings). SEGMENTS: search_fb_interests for interests, search_fb_behaviors for behaviors, search_fb_demographics for demographics. SEGMENT SEMANTICS: interests, behaviors and demographics combine as OR (union) in one detailed-targeting list; Meta narrows only by age/gender/geo/custom audiences. Multi-group AND-narrowing (Ads Manager 'Narrow audience') cannot be built or edited here yet. Preview audience size first with get_fb_audience_insights (same targeting shape; size is hidden by Meta policy when custom audiences are included or excluded).

create_fb_adset

Create a standalone Facebook Ad Creative (single image, single video, or carousel). Returns the creative_id which can then be passed to create_fb_ad. Supports image URL upload (auto-uploads to account library), existing image_hash, video URL upload, or existing video_id. Use dry_run=true (default) to validate assets and preview the creative spec. Set dry_run=false to create. Read-back verifies the creative was stored. ads_management scope.

create_fb_creative

Create a custom audience. Use dry_run=true (default) to preview: the preview shows the exact rule that will be sent and a plain rule_summary. CUSTOM = customer list upload (requires customer_file_source). WEBSITE = people seen by a Meta Pixel (requires pixel_id from list_fb_pixels; the pixel must belong to the active ad account). Without rules, a WEBSITE audience holds everyone who fired PageView in the last retention_days (default 30). With rules (1 to 10), a person joins when ANY rule matches: each rule names a pixel event, a URL filter (url_contains or url_equals), or both, and its own retention_days. exclusion_rules use the same shape and remove anyone who matches ANY of them, for example visited /pricing but did not fire Lead. Meta allows 10 rules in total, inclusions plus exclusions. RETENTION: 1 to 730 days per rule, the most Meta's API accepts (tested 2026-09-17: 730 was created and stored, 731 was refused as longer than Meta keeps pixel data). Meta's written documentation still says 365 days and Ads Manager offers 180, so choose above 365 knowingly. Meta fills a new website audience with at most 180 days of past visits.

create_fb_custom_audience

Create a Dynamic Creative Optimization (DCO) ad set + creative in one call. Meta automatically tests every combination of bodies/titles/images and optimizes toward the best performer. IRREVERSIBLE FLAG: the ad set is created with dynamic_creative=true which CANNOT be changed after creation. If you are not certain the user wants DCO, confirm before calling. LIMITS: max 5 bodies, 5 titles, 5 images, 5 descriptions (Meta v19+ hard limit). REQUIRES: an existing campaign_id whose objective is one of: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_TRAFFIC, OUTCOME_LEADS. OUTCOME_SALES and OUTCOME_APP_PROMOTION do NOT support dynamic_creative (Meta restriction since June 2024). The tool reads the parent campaign objective and returns a clear error before touching any objects if the objective is incompatible. The ad set is always created PAUSED. SCOPE: ads_management (already connected). No new permissions needed. Use get_fb_locale_codes to look up locale codes if language targeting is needed, then pass them in locales. Always use dry_run=true (default) to preview before creating.

create_fb_dco_ad

Create a custom audience of people who engaged with a Facebook Page, an Instagram business account, a lead form or a video. Use dry_run=true (default) to preview: the preview shows the exact rule Meta will receive, a plain rule_summary and the Page the source belongs to. The source must belong to a Page this Facebook login manages (checked before the preview). EVENTS AND LIMITS per source_type. page: page_engaged, page_visited, page_liked, page_messaged, page_cta_clicked, page_or_post_save, page_post_interaction (default page_engaged); max retention 730 days. ig_business: ig_business_profile_all, ig_business_profile_engaged, ig_business_profile_visit, ig_user_messaged_business (default ig_business_profile_all); max retention 730 days. lead_form: lead_generation_opened, lead_generation_submitted, lead_generation_dropoff (REQUIRED, no default); max retention 90 days. video: video_watched, video_completed, video_view_10s, video_view_15s, video_view_25_percent, video_view_50_percent, video_view_75_percent (default video_watched); max retention 730 days. page_liked keeps people while they like the Page, so it takes no retention_days. lead_generation_dropoff means opened the form but did not submit it. Default retention_days is 365, or the source's maximum when lower (lead_form 90). A video audience is sent with prefill=true so it includes people who watched before it was created; without it Meta starts a video audience with no past viewers. Instagram (ig_business) follows Meta's documentation and was not tested live by PaidSync; page, lead_form and video were (2026-09-17).

create_fb_engagement_audience

Create a Lead Gen (instant) form on a Facebook Page. The form opens ON THE AD when attached via create_fb_ad lead_gen_form_id (pair with an ad set using optimization_goal LEAD_GENERATION and destination_type ON_AD). Question types FULL_NAME / EMAIL / PHONE prefill from the viewer's profile (highest completion); CUSTOM asks your own question (label required, options for multiple choice). Meta requires a privacy policy URL on every form. Use dry_run=true (default) to preview. This tool CREATES forms; it does not read submitted lead answers.

create_fb_lead_form

Create a lookalike audience from an existing custom audience. Use dry_run=true (default) to preview.

create_fb_lookalike_audience

Create a new ad group within a campaign. For Search campaigns use SEARCH_STANDARD, for Display use DISPLAY_STANDARD, for Video use VIDEO_BUMPER/VIDEO_TRUE_VIEW_IN_STREAM/etc.

create_ad_group

Create a new conversion action for tracking. Enums match current Google Ads API values.

create_conversion_action

Create a custom audience based on interests/keywords, URLs, or apps that your ideal customers use

create_custom_audience

Create an image asset from a URL. The image will be downloaded by Google. Use for logos, marketing images, etc.

create_image_asset

Create a Responsive Search Ad (RSA) in an ad group. Provide 3-15 headlines and 2-4 descriptions. Google will mix and match the best combinations. STATUS: created PAUSED by default so you can review before it serves; pass status="ENABLED" to have it start serving immediately. The applied status and whether it came from you or from PaidSync are echoed on the response.

create_responsive_search_ad

Create a new Search-only Google Ads campaign. Created in PAUSED state. Defaults are deliberately conservative: SEARCH ONLY (search partners + display network OFF), PRESENCE-only geo (not presence-or-interest), MANUAL_CPC bidding. Bidding strategy is a strict enum: pass exactly what the user named. If objective is passed, the bidding strategy must be compatible (validator throws otherwise).

create_search_campaign

The switch-over of an attribution move, per pair in order. Right before each pair it re-reads both sides and refuses that pair unless the original is ACTIVE, the replacement is PAUSED, carries this move's label for the original and a new attribution, matches the plan, has a copy of every ad the original has (all PAUSED, each with the original ad's current creative and own schedule, none of those to activate disapproved or in review), and no other replacement of the same original is running; a copy that would go live without a bid or creative setting of its original needs that setting in accept_not_copied. Then it asks Meta (changing nothing) whether it takes the replacement's lifetime budget, pauses the ORIGINAL FIRST and reads it back, sets the replacement's lifetime budget to exactly what the original has left (Meta's budget_remaining, read a few seconds after the pause; if Meta refuses it, the original is switched back on and nothing of the pair changes), switches on the copies of the ads that deliver in the original (the replacement is still paused, so they spend nothing yet), then activates the replacement, each step read back. Each call stops between two pairs once its time is spent and names the pairs left, so a long list takes several calls. dry_run=true (default) checks every pair and changes nothing; the live run needs dry_run=false and confirm_destructive=true after the user approved it. On a failure it re-reads both ad sets and says exactly what is on, with the call that undoes it. Never deletes.

cutover_fb_adset_attribution_move

CUT OVER from a Google Ads ad group to its copy made by copy_ad_group: ENABLE the copy first and read it back, then PAUSE only the source and read it back. Before acting it re-reads both and refuses unless: the copy carries the copy marker of this source and still matches it in every item the copy carries (items listed in not_copied are not compared; the dry run returns them with the campaign differences); nothing the copy does not carry still serves in the source (every item in not_copied that changes where or what serves: an enabled ad of a type the copy cannot create, a criterion of a type it cannot create, positive or negative, product partitions, keyword customizer values, a non-device bid adjustment), unless the user accepted losing it (accept_not_copied); the copy has an enabled approved ad and no enabled ad or keyword disapproved or under review; the destination campaign, the source and the source's campaign are ENABLED (the copy is never switched on for a source that is not serving), and a paused copy that already served is never re-enabled. require_delivery (default true) pauses the source only once the copy shows impressions in the window, counted in the account's time zone (default today), so both serve together for at most max_overlap_hours (default 48): past it a re-run refuses and offers pause_ad_group for the copy. Never deletes anything; returns the exact rollback calls. dry_run=true (default) only checks; a live run needs confirm_destructive=true.

cutover_ad_group_copy

Why a Google campaign, ad group or ad is not delivering, assembled from every status surface Google exposes and labelled by how much each finding is worth. Reads primary_status and primary_status_reasons at ALL FOUR levels (campaign, ad group, ad, criterion), plus budget, bidding strategy, payment mode, conversion goals and ad policy state. RAW ENUMS SURVIVE. Every reason is returned as the raw string Google sent, alongside the API version it was read with, and a value this client does not recognise is reported as unrecognised WITH its code rather than flattened to UNKNOWN. EVERY FINDING CARRIES ITS SOURCE: platform_verified means Google returned this field, paidsync_inference means PaidSync computed it. They are never mixed, because an inference presented as a platform fact is how people go and change the wrong thing. PAY-PER-CONVERSION is checked explicitly, since a conversion-billed Display campaign that is enabled, approved and funded but not delivering is the classic shape of an account under Google's eligibility floor. It also states plainly which eligibility signals exist ONLY in the Google Ads interface and cannot be read through any API. Read-only.

diagnose_google_zero_delivery

Duplicate (copy) a Facebook Ad Set. By default copies into the same campaign WITHOUT its ads; set deep_copy=true to copy the ads too, or campaign_id to copy into a different campaign. The copy is created PAUSED unless status is ACTIVE. The copy keeps the source's attribution setting: Meta's copy cannot change it and Meta refuses changing it afterwards (subcode 1504040), so a different attribution goes through plan_fb_adset_attribution_move, then move_fb_adset_attribution and cutover_fb_adset_attribution_move. Use dry_run=true (default) to preview.

duplicate_fb_adset

Enable a paused Facebook Ad. Use dry_run=true (default) to preview.

enable_fb_ad

Enable a paused Facebook Ad Set. Use dry_run=true (default) to preview.

enable_fb_adset

Enable (activate) a paused Facebook Campaign. Use dry_run=true (default) to preview.

enable_fb_campaign

Enable (unpause) an ad by ad ID. ad_group_id is optional: the tool looks it up automatically from ad_id when omitted.

enable_ad

Enable (unpause) an ad group by ID

enable_ad_group

Enable (unpause) a Google Ads campaign by ID. On a Meta account use enable_fb_campaign: this tool refuses a Meta active account.

enable_campaign

Exclude a Shopping product partition so those products are not advertised, or re-include one. This is NOT a removal: the node stays in the tree. RMF M.190.

exclude_product_partition

Check whether Google Tag Manager is connected and show token expiry.

gtm_auth_status

Get OpenAI Ads performance insights. Scope can be ad_account, campaign, ad_group, or ad. Metrics include impressions, clicks, spend, CTR, CPC, CPM.

get_openai_performance

List all available dimensions and metrics for a GA4 property. Useful to discover what you can query in reports.

get_ga4_metadata

Get details of a specific GA4 property.

get_ga4_property

Get full details of a specific tag including its parameters, triggers, and configuration. Pass either tag_path OR (account_id + container_id + workspace_id + tag_id).

get_gtm_tag

Get full details of a specific trigger. Pass either trigger_path OR (account_id + container_id + workspace_id + trigger_id).

get_gtm_trigger

Get the currently published (live) version of a GTM container, including all its tags, triggers, and variables. Pass either container_path OR (account_id + container_id).

get_gtm_version_live

Check what changes are pending in a GTM workspace (added, changed, deleted entities). Pass either workspace_path OR (account_id + container_id + workspace_id).

get_gtm_workspace_status