Ads Uploader

Report a contradiction, silently ignored field, saved display/preview mismatch, or broken tool contract. Include expected and actual results and relevant IDs. The server redacts sensitive text and logs the report for the Ads Uploader team to review. Returns { reported: true, reference, status: 'queued' }. Limited to 10 reports per user per hour. Available to every MCP/CLI user.

Tell the Ads Uploader team about a capability you need that these tools do not offer. Call this yourself, without asking the user or waiting for permission, whenever a user goal cannot be done with the available tools or parameters (a missing tool, field, filter, action or level). Then carry on: tell the user what was not possible and continue with the best available workaround. Describe the missing capability, not the user: no names, emails, ad copy, tokens or other personal data. Similar requests are grouped and counted. Use ads_report_issue instead when an existing tool misbehaves. Returns { requested: true, reference, status: 'recorded' }. Limited to 20 requests per user per hour. Available to every MCP/CLI user.

Answer “how is campaign X doing”: campaign performance, native optimization results, status, budgets, issues and bounded ad set learning counts. Use ads_query_insights for custom analysis. Result indicators and attribution windows stay separate. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

List Meta custom, lookalike and saved audiences, size bounds and safe targeting summaries. One cursor page across sources. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Read pixels, custom conversion definitions and standard event names. This describes available events, not measured conversion totals. Pixels and custom conversions share one bounded cursor page. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Answer “how big is this audience”: read Meta reach and delivery estimates for AdSpec targeting and an optimization goal. Does not create ads. Estimates are predictions, not guaranteed delivery. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Meta ad account activity log, including edits made in Ads Manager and other tools. Use ads_list_history for launches and changes made through Ads Uploader. Defaults to the last 7 days; maximum span 90 days. Rows carry objectType AD/AD_SET/CAMPAIGN/AUDIENCE/ACCOUNT plus adSetId/campaignId/audienceId; metaObjectType and extra_data keep Meta’s legacy names (extra_data.campaign_id on an ad is its ad set). Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Read images or videos in the Meta ad account library, separate from Ads Uploader uploads. Returns one cursor page. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Read accessible Facebook Page promotable posts or media for a connected Instagram professional account. Supply exactly one of pageId or igUserId. Messages are limited to 500 characters. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Read an owned Meta ad account’s status, currency, timezone, spend and funding display. Money includes major amounts and raw minor-unit strings. Includes the read-only metaEdits enabled setting and approval rule, plus permissions (visible, read, launch and edit as off, approval or allowed, approvalRule) from the Account Permissions page; CLI/MCP cannot change them. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Read retained Agent Inbox suggestions and direct edit outcomes over the last 90 days, newest first. Includes reason, reasonEdited, runTitle, clientName, before/after, outcome and a plain error, plus userEdited {value, note} with the agent’s own suggestedAfter and suggestedReason when the user changed them (for example, you suggested 6000 and the user changed it to 6100), and revisions[]: every later change, oldest first, with at, by (user or agent, plus source and clientName), kind (value or note), action (edited, or restored_to_agent when your original was put back), field, before and after; revisedAt is the latest. Partial duplicates also include failedStep. Filter by accountId, campaignId, since/until, reviewId (run), status, kind or action; use paging.cursor with the same filters for more. Time is resolution time when present, otherwise suggestion creation time. waiting includes applying; failed includes partial outcomes. Direct edit campaign filters match campaign IDs recorded with those edits. Read permission is required and hidden accounts are excluded. Does not call Meta or change anything.

Ads Uploader History: launches and changes made through Ads Uploader (web Uploader, Duplicator, AI Edits, CLI, MCP, API) on one ad account, newest first — the same list as the History page. Duplicator copies read type Duplicate, with duplicate: copy or post. Not Meta's activity log.

Read one Ads Uploader launch: one row per ad with its ID, name, status, ad set, campaign, result and error, plus totals and failures. Use a launchId from ads_list_history rows. detail: 'full' adds targeting, budgets, schedule, creative settings and media.

Cancel pending AI edit suggestions so they leave your Agent Inbox. Nothing changes in Meta. Pending only; returns a result per suggestion. To clean up the same suggestion pending in two reviews, call with the older reviewId and duplicatesOnly: true. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Discard a launch waiting in your Agent Inbox, like its Discard button. Nothing is created in Meta. The saved build stays; use ads_delete_build to remove it as well. Launches that already started cannot be discarded. Use ads_edit_cancel for edit suggestions. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Read compact account-scoped Edit Review counts, including building reviews. Proposals are omitted unless include: proposals. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Read one owned review with compact proposal rows, statuses and edit IDs. Each row has userEdited {value, note}; when the user changed your suggestion before approving it, suggestedAfter and suggestedReason hold what you suggested and after and reason hold what the user chose; revisions[] lists each change with who made it, before and after, and restored_to_agent when your original was put back. Duplications include copies[].status (pending, approved, made, partial, failed, rejected), group for split post requests, and review-wide summary.copies totals including partial. A partial copy already exists: report its id, currentName, failedStep, plain error and retry hint; retry only that step from your Agent Inbox, never run the copy again. Returns 50 proposals by default; use paging.after for more or detail: full for full proposal data. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Preview status, archive, delete, name, budget, bid including minimum ROAS, schedule, spend-limit, targeting, ad set settings and set_creative edits. Targeting is patched; use ads_search_targeting for IDs and request detail: full to inspect the full resulting audience in the preview. To change an image or video, create a new ad in the Uploader. At most 10 creative edits per plan. Show ENGAGEMENT_RESET prominently: likes, comments and shares stay with the old post. Supports placement-customised creatives (for example a 4:5 feed + 9:16 story/reels pair) and multi-media dynamic asset feeds while preserving media and routing. Multiple text rows require texts arrays; labelled rows require the same count and order. Non-carousel placement feeds allow one description; multi-CTA edits are refused. Carousels (plain and placement-customised) support primary text, whole-carousel link/CTA/display link/URL tags and per-card headline/description/link via cards[{card, headline, description, link}]; per-card links are refused on placement-customised carousels. Unsupported flexible, catalog, partnership, language or segment customization, and unknown asset-feed optimization types return precise reasons; relaunch with ads_create (CLI: ads create) using the same media or the Uploader copy-settings-from-this-ad flow. Review mode queues proposals without Meta validation; Meta decides at apply and results show per item. Edits that already match Meta return NO_CHANGE warnings; when every change already matches, review mode queues nothing and returns nothingQueued: true with no reviewId or reviewUrl, so tell the user nothing needs approval. Default previews summarize items and group warnings; detail: full includes changes and details. Passing reviewId moves identical pending suggestions from other reviews into that review (their old copies are cancelled); without reviewId identical pending suggestions are reused where they are. Pass idempotencyKey and reuse the same key on retry after a time

Apply an approved preview plan to existing Meta objects. Inspect every per-change result: applied, failed, skipped or pending. Pending means not sent yet, still waiting in the review; apply the same review again to send them. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Create a new preview restoring applied reversible changes from an edit. Returns not_reversible for archive and delete. Does not apply the undo. In review mode the undo keeps the original run title and note, prefixed "Undo:", unless you pass runTitle or reason; pass reviewId to add it to an existing review. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Deprecated: use ads_list_history with type changes. Read one account-scoped cursor page of Ads Uploader edit history. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Read an owned edit and its applied, failed, skipped and pending changes. Pending means not sent yet, still waiting in the review; apply the same review again to send them. Both preview detail levels report settings.launch (allowed, approval or off) separately from the edit mode; settings.approvalRuleAppliesTo is edits. Edit approval does not gate new-ad launches. Review mode returns reviewUrl and no executable plan. Share reviewUrl with the user, do not apply, and reuse reviewId on later previews in the same conversation. EDITS_REVIEW_REQUIRED means approval must happen in your Agent Inbox. Always preview and show the user the changes. Set a confirm flag only after the user explicitly approves that change. Never retry a partial apply blindly. Archive and delete cannot be undone. Preview requests accept optional reason and runTitle. A per-operation reason overrides the top-level reason for that operation. Use one short evidence-based note for the Agent Inbox and reuse runTitle with the same reviewId.

Show which Ads Uploader user this session is authenticated as (email, name, user ID) and the API host it talks to. Use this to verify the tool session matches the account the user is logged into on the web before editing builds or creating ads.

Takes no parameters.

List Meta ad accounts available to the authenticated Ads Uploader user. Use refresh to re-check Meta for reinstated/changed accounts (rate limited).

List campaigns in an ad account, optionally filtered by name search and status. Search matches campaign names only; to find ad sets or ads by name, call ads_list_adsets or ads_list_ads without a parent ID. Use fields to return only the columns you need; large pages are trimmed to fit the output budget.

List ad sets in a campaign, or across the whole ad account when campaignId is omitted. To find ad sets by name without knowing their campaign, omit campaignId and pass search (name contains); each row then includes campaignId and campaignName. status defaults to 'active', so pass 'all' to include paused ad sets. Returns one bounded page; follow paging.after for more. Use fields to return only the columns you need; large pages are trimmed to fit the output budget.

List ads in an ad set, or across the whole ad account when adSetId is omitted. To find ads by name without knowing their ad set, omit adSetId and pass search (name contains); each row then includes adsetId, adsetName, campaignId and campaignName. status defaults to 'active', so pass 'all' to include paused ads. To see why ads were rejected or have delivery issues, add reviewFeedback and/or issues to fields (Meta's policy reasons and issues_info); they are read only when named in fields. Returns one bounded page; follow paging.after for more. Use fields to return only the columns you need; large pages are trimmed to fit the output budget.

Get one ad with its creative details. For a DISAPPROVED or WITH_ISSUES ad it also returns reviewFeedback (Meta's rejection reasons: global and placementSpecific lists of policy and reason) and issues (errorCode, errorSummary, errorMessage, level), so you can tell the owner why it is not delivering; null means Meta's reasons could not be read.

List Facebook Pages (with their connected Instagram accounts) available for profile overrides in an ad account.

Search Meta targeting values for ads_create, a saved build spec, or set_targeting in ads_edit_preview. Use type=city to find targeting.cities[].key values, type=zip to find targeting.zips[].key values, or type=detailed for {id,name,type} entries. Builds use targeting.detailedTargetingGroups; edits use add/remove with the returned type and {id}. IDs must never be guessed; use this tool to discover them.

Discover Ads Insights fields by search, group or ids. Without filters, returns a compact group index and recommended fields. Add accountId to discover custom conversions. Breakdown IDs must be requested through ads_query_insights.breakdowns, not fields. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

Query one bounded page per account of Ads Insights for one account or 2 to 5 accountIds, with table rows by default. Use friendly metrics such as leads, purchases and roas for business questions. Omitted counts and values are 0 with delivery (impressions > 0) and null otherwise; a positive count without an action value stays null. Native result indicators with empty values are 0 on delivered rows; cost per result stays null for zero results. Use results and cost_per_result to assess optimization goals at campaign, ad set or ad level. Missing native results can be derived from ad set setup and delivery; incomplete data stays unknown. Discover fields by search or group. Asset breakdowns analyze flexible or dynamic creative ads; use each alone. For audience segment mix (prospecting / engaged / existing customers) use breakdowns: [user_segment_key] alone, with timeIncrement weekly or monthly for share of spend over time. Request only needed columns and use paging.after to continue only when needed. Reach, frequency, and CTR are non-additive, so never sum them across rows. Empty rows are successful. Zero-impression rows are excluded by default (excludeZeroImpressions: true); set false to include zero rows. Compare keeps a row if either period has impressions above zero, including drops to zero. Use compare for vs last period or previous-year questions. Requested fields stay visible; friendly formulas are evaluated per period and native result values match by indicator and attribution window. Uncomparable fields retain current values with COMPARE_FIELD_UNSUPPORTED listing the fields. Use include for status, budget, targeting or creative context instead of separate list calls. Targeting geo includes countries; country_groups with key/label (eea = European Economic Area (EEA)); region and geo-market names; cities with radius/unit; zip/custom-location samples; location_types; and the same fields under geo.excluded. Each list is capped at 25 with full singular counts (country

Check an Insights report job returned by ads_query_insights. Use job.id and the same accountId; never re-submit the query to poll. A running result includes progress and pollAfterSeconds. A completed result is one bounded page; use paging.after with this tool for more rows. On 429, respect Retry-After and do not retry in a loop. Reporting 429 responses carry Retry-After. ROW_QUOTA_EXCEEDED means wait until meta.quota.resetsAt (or the error quota reset); do not retry before then.

List saved API or ad text presets for an ad account.

Get one saved preset by ID.

Save an existing ad as a reusable API preset.

List saved uploader build summaries for the authenticated user, optionally filtered by ad account. Returns metadata, warning codes, totalAdSets/totalAds/complete from display, and mediaCount. Use ads_get_build for full detail.

Create a durable saved build for the authenticated user. A spec-only build is supported and preferred for agent-created configurations because the web uploader hydrates it and generates its own webState on resume. Portable specs support the full v1 launch surface, including campaign-qualified texts.perAdset entries and per-campaign profile.campaigns identity overrides. Web-captured builds can launch without uploadId when spec.mediaItems carries a mediaHash for every image and mediaId for every video, with missing library-video thumbnails recovered from Meta at preview/create. Do not construct webState by hand. Only provide webState when round-tripping a webState previously read from a build without changing its structure. accountId is optional when it can be derived from webState.selectedAccount.accountId, webState.selectedAccount.account_id, or spec.accountId. Confirm that the build was saved. If the user has an open uploader tab, do not repeat the returned url; share it only when the user asks for it or says the tab is closed. For a new headless build with no open uploader tab, give the returned url so the user can open and review it. Use ads_create with buildId to launch it when spec.launchable is true. launchable only describes headless ads_create launches; a launchable:false build still opens and can be edited in the web uploader. Unresolved video identifiers must be repaired before launch. Missing library-video thumbnails are recovered from Meta at preview/create; only the thumbnail image is uploaded, never the video. For videos, mediaItems[].mediaId MUST be the numeric Facebook video id from the upload response videoId, not its internal id. videoId is accepted as an alias. linkedAssets[] follow the same rule. Internal upload ids are resolved on save only for uploads owned by the authenticated user in the selected account; otherwise a video without a numeric id or batch link makes the build unlaunchable. Canonical 4x5 primary with linked 9x16 item: {"mediaName

Get one saved build by ID. Returns the full spec without truncation. The opaque web uploader session snapshot webState is also included by default; pass include: ["-webState"] to omit it. Update spec for content changes and do not reconstruct webState. Other metadata is trimmed for display.

Fork a saved build into a new autosaved draft. Use this instead of editing the existing build when the user wants a variant and the original must stay intact. The fork copies the uploader configuration and media references, receives a new build ID, and can be edited independently. Confirm that the fork was created; share its URL only when the user asks for it or says there is no open uploader tab. Preset-only requests reuse the saved campaign and ad set, including saved builds. Preview and create add a non-fatal PRESET_DESTINATION_USED warning. Use campaign.name or named multi-campaign entries for new campaigns, or campaign.id / adSet.id to override the saved destination. With campaign.id alone, new ad sets are created. copyFromAd behavior is unchanged.

Update one saved build by ID: rename it, edit notes, patch its portable spec, or deliberately replace its full spec/webState. Uploaded-media partnerships support profile.partnership for a shared Second Identity and texts.perAd/perAdset sponsor overrides, including both IDs null for No Partner. These builds launch through the CLI and MCP and hydrate their identities in the web uploader. Approval is rechecked at preview and launch. Prefer specPatch for content edits: omitted fields survive and nested text entries merge field-by-field, so changing headlines does not clear link, displayUrl, CTA, URL tags, or AI disclosure. Uploaded-media texts.perAd keys are file names or media:<uploadId>; a file name that two uploads share is refused, so rename one or use media:<uploadId>. CTA fields use Meta enum values such as SHOP_NOW. Standard ads normalize human labels such as Shop Now; imported partnership posts require the enum and do not normalize labels. specPatch requires the revision from ads_get_build as expectedRevision. Send edits to a build one at a time, never in parallel. Changes to spec, webState, mediaItems or uploadBatchId bump the revision. A rename or notes-only update does not bump it. Batch many ad edits into one specPatch where you can. On "Build changed since it was read" (HTTP 409), call ads_get_build again and retry with its current revision as expectedRevision. Use spec only for a full rewrite because it replaces the whole portable spec. Do not construct webState by hand; only round-trip an unchanged webState previously read from the build. When only portable spec changes, the web uploader regenerates webState on next resume. Setting a name promotes an autosaved build to a kept, named build. Returns updated metadata only; call ads_get_build again to read the stored state. Confirm that the update was saved; an open uploader tab picks it up automatically. Share the build url only when the user asks for it or says the tab is closed. Do not surface webStateStal

Delete one saved build by ID.

List recent media upload batches for an ad account.

Get a completed upload batch by batchId (or its alias uploadId), or poll a background media-ingest job by jobId until complete is true. Job polls return the full result, progress and file list by default; pass compact:true for counts and failed files only.

Upload media to an ad account. Use paths for local disk media, files[].url for public URLs or Google Drive file links, or driveFolderUrl for a public Drive folder. URL and Drive modes return a background jobId to poll with ads_get_upload. Base64 is only for a couple of small images; presigned mode is only for byte-capable environments. In presigned mode, script:true is recommended for agents with a shell.

Refresh expired upload links for selected files or multipart part numbers in the same batch. Keep successful uploads. Single-PUT file keys may change; use the returned keys when finalizing.

Finalize a presigned upload batch after the client has PUT each file. Hosted calls return a background ingest jobId; poll it with ads_get_upload.

For existing destinations use campaign.id and adSet.id (never existingCampaignId or existingAdSetId); campaign.name and adSet.name request new destinations. For standard ad text use headlines arrays, e.g. texts.perAd["photo.jpg"] = { headlines: ["New headline"] }, or texts.common.headlines for shared copy. A singular headline string is accepted as a one-element alias; conflicting headline/headlines values are rejected. Create ads from a v1 AdSpec request body or saved build, including Instagram existing-post partnership ads with common, per-ad-set, or per-ad sponsors and text. Import by Instagram URL, shortcode, source ID, or ad code in mediaItems. Uploaded media supports Facebook and Instagram partnerships: set profile.partnership.enabled, shared or campaign sponsors, and texts.perAd/perAdset sponsors. Null both row sponsor IDs means No Partner; sponsorPageUseInstagramAccount supports Instagram-only partners. Approval is checked for the effective First Identity. Omit uploaderMode for uploads. Facebook post imports, mixed post/upload batches and Threads on imported posts are unsupported. Uploaded-media texts.perAd keys are file names or media:<uploadId>; a file name that two uploads share is refused, so rename one or use media:<uploadId>. CTA fields use Meta enum values such as SHOP_NOW. Standard ads normalize human labels such as Shop Now; imported partnership posts require the enum and do not normalize labels. Saved builds with mediaItems launch only those selected items and their linked placements; upload batches supply missing media details. Without mediaItems, uploadId selects the whole batch. Launch is refused when the planned ad count differs from a complete saved display. Missing library-video thumbnails are recovered from Meta at preview/create without re-uploading the video. Supports campaign-qualified texts.perAdset overrides and per-campaign profile.campaigns identities in multi-campaign launches. Local polling blocks until the server job completes or th

For existing destinations use campaign.id and adSet.id (never existingCampaignId or existingAdSetId); campaign.name and adSet.name request new destinations. For standard ad text use headlines arrays, e.g. texts.perAd["photo.jpg"] = { headlines: ["New headline"] }, or texts.common.headlines for shared copy. A singular headline string is accepted as a one-element alias; conflicting headline/headlines values are rejected. Preview a v1 AdSpec or saved build, including uploaded-media partnerships and Instagram existing-post partnership imports. Returns newAdSets with the exact settings each new ad set will be created with (targeting, placements, attribution, optimization, pixel/event, bid, budget). Uploaded-media previews report effective sponsors, approval and header mode per ad and ad set. Resolves posts and checks Meta permissions using read/validate-only calls without creating ads or storing codes. Returns per-ad creators, sponsors, optional text, authorization status, warnings, and a code-free resolvedSpec. Supply transient codes again at create. Uploaded media supports Facebook and Instagram partnerships: set profile.partnership.enabled, shared or campaign sponsors, and texts.perAd/perAdset sponsors. Null both row sponsor IDs means No Partner; sponsorPageUseInstagramAccount supports Instagram-only partners. Approval is checked for the effective First Identity. Omit uploaderMode for uploads. Facebook post imports, mixed post/upload batches and Threads on imported posts are unsupported. Previews always return warnings and lifetimeBudget when applicable. New campaigns/ad sets mark lifetime end-date warnings blocking: true and create rejects them with HTTP 400. Set options.schedule.endTime at least 24 hours after the start or use a daily budget. Existing ad set warnings stay non-blocking. Missing library-video thumbnails are recovered from Meta at preview/create; only the thumbnail image is uploaded, never the video. For videos, mediaItems[].mediaId MUST be the numeric

Get or resume an ad creation job by jobId. Returns the full result and original stage progress by default. Pass compact:true for an ads summary with created/failed/total counts and progress measured in ads. Includes the last 20 progress.operations (operations:"full" returns all retained operations). After ads_create returns still_running, poll until complete is true; compact running jobs include a nextStep hint.

Duplicate campaigns, ad sets or ads, the same as Ads Manager's Duplicate. This is the default way to duplicate: use it whenever the user asks to duplicate, copy or clone. Optional reason is one short evidence-based note for the user in their Agent Inbox. Optional runTitle names this batch of suggestions. Pass the reviewId from an earlier preview or duplicate in this conversation to add the copy to that review, so the user approves the run together. Deep copy includes children by default; deepCopy:false copies only the root. Destination must be in the same account; ad sets default to their source campaign and ads to their source ad set. Rename supports {name}, {date} (UTC), {index}; only roots are renamed unless renameChildren:true. Roots default to PAUSED; children inherit source status unless childStatus:PAUSED. Preview warns about ACTIVE children inside a paused copy and flags flexible, partnership, Instagram-post and catalog ads that may not copy exactly; review copied ads before activating. Targeting, schedule and ad set settings overrides apply to copied ad sets. Ad set copies accept budget and bid_strategy overrides when the destination campaign uses ad set budgets (ABO), including copies from campaign-budget (CBO) campaigns. CBO-to-ABO ad set copies require overrides.budget.daily; preview returns ADSET_BUDGET_REQUIRED without a budget. Meta gives these copies a daily budget, so only a daily budget override is supported. Switching a copy between daily and lifetime budgets is refused at preview with BUDGET_TYPE_CHANGE_UNSUPPORTED, including ad sets inside deep campaign copies and CBO campaign copies. Source CBO ad sets have no budget of their own; the source campaign budget is never carried over. For CBO-to-ABO copies, overrides.bid.bid_strategy is required for capped or minimum-ROAS source campaigns or source ad sets with bid amounts or constraints (ADSET_BID_STRATEGY_REQUIRED); otherwise the strategy defaults to LOWEST_COST_WITHOUT_CAP. An explicit strategy t

Duplicate campaigns, ad sets or ads, the same as Ads Manager's Duplicate. This is the default way to duplicate: use it whenever the user asks to duplicate, copy or clone. Optional reason is one short evidence-based note for the user in their Agent Inbox. Optional runTitle names this batch of suggestions. Pass the reviewId from an earlier preview or duplicate in this conversation to add the copy to that review, so the user approves the run together. Deep copy includes children by default; deepCopy:false copies only the root. Destination must be in the same account; ad sets default to their source campaign and ads to their source ad set. Rename supports {name}, {date} (UTC), {index}; only roots are renamed unless renameChildren:true. Roots default to PAUSED; children inherit source status unless childStatus:PAUSED. Preview warns about ACTIVE children inside a paused copy and flags flexible, partnership, Instagram-post and catalog ads that may not copy exactly; review copied ads before activating. Targeting, schedule and ad set settings overrides apply to copied ad sets. Ad set copies accept budget and bid_strategy overrides when the destination campaign uses ad set budgets (ABO), including copies from campaign-budget (CBO) campaigns. CBO-to-ABO ad set copies require overrides.budget.daily; preview returns ADSET_BUDGET_REQUIRED without a budget. Meta gives these copies a daily budget, so only a daily budget override is supported. Switching a copy between daily and lifetime budgets is refused at preview with BUDGET_TYPE_CHANGE_UNSUPPORTED, including ad sets inside deep campaign copies and CBO campaign copies. Source CBO ad sets have no budget of their own; the source campaign budget is never carried over. For CBO-to-ABO copies, overrides.bid.bid_strategy is required for capped or minimum-ROAS source campaigns or source ad sets with bid amounts or constraints (ADSET_BID_STRATEGY_REQUIRED); otherwise the strategy defaults to LOWEST_COST_WITHOUT_CAP. An explicit strategy t

Duplicate ads while keeping their social proof (likes, comments, shares) by reusing the same Page post. Only use this when the user asks to keep engagement; for regular duplication use ads_duplicate. Optional reason is one short evidence-based note for the user in their Agent Inbox. Optional runTitle names this batch of suggestions. Pass the reviewId from an earlier preview or duplicate in this conversation to add the copy to that review, so the user approves the run together. Copies follow the account's Agent Launch setting on the Account Permissions page, like launches; Agent Edit does not apply. Allowed (the default) starts the job directly. Approval returns status "pending_approval" with reviewUrl; nothing is duplicated until the user approves in your Agent Inbox. Share the link; do not retry. Off refuses with AGENT_LAUNCH_DISABLED. Post-ID copies never require confirmSpend (it is accepted and ignored). Select ads by Page post ID into an existing ad set or new cloned ad set. Use postIds for discovery or adIds for exact selection, never both. Preview returns sourceCandidates and a pinned resolvedRequest. Ambiguous matches require explicit adIds; warned live runs require acknowledgeWarnings:true or useCreativeId:true. New ad sets: newAdSet and newAdSetPerAd copy the ad set given in adSetId, which must already be in the destination campaign and may be empty (it needs no ads). For a brand-new empty campaign, first put one ad set in it with no ads (for example ads_duplicate of an ad set with deepCopy:false), then call ads_duplicate_by_post with that adSetId and newAdSet or newAdSetPerAd for each group, so the ads and their new ad sets are created in the by-post step. Do not duplicate the ads into the template ad set itself. This blocks until the duplication completes or the 30 minute ceiling is reached. If it returns status "still_running", call ads_get_duplication with the returned jobId until complete is true.

Duplicate ads while keeping their social proof (likes, comments, shares) by reusing the same Page post. Only use this when the user asks to keep engagement; for regular duplication use ads_duplicate. Preview existing Meta ads selected by Page post ID without creating anything. Use postIds for discovery or adIds for exact selection, never both. Preview returns sourceCandidates and a pinned resolvedRequest. Ambiguous matches require explicit adIds; warned live runs require acknowledgeWarnings:true or useCreativeId:true. Returns a cleaned source-to-destination plan and never exposes raw Meta payloads.

Get a regular duplicate or duplicate-by-post job by jobId. After ads_duplicate or ads_duplicate_by_post returns still_running, poll until complete is true. Inspect created, failed and skipped objects for copy jobs. A partial job has created objects: report newId and current name from created, plus stage and error.message from failed. retryable marks a saved retry; retry only the failed step from your Agent Inbox, or change the existing object in Ads Manager when unavailable. Never run the copy again; it would create a second copy. Pending approvals have no job until the user approves in your Agent Inbox.

Cancel a running ad creation job or media ingest job.