API reference

Launches

Create, edit and publish launches: batches of ad sets and ads for a Meta or LinkedIn or X ad account.

GET/launches

List launches

Most recently changed first, or in the order sort and dir ask for: the order, the filters and the cursor hold over every page.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
statusquerystringOptionalLaunch status: draft, publishing, published or failed, several comma-separated.
adAccountIdquerystringOptionalAd account, several comma-separated.
sortquerystringOptionalThe order: updated (default), created, published, archived, name, status (draft, publishing, published, failed) or ads.
dirquerystringOptionalasc or desc; left out, the order's own (times and counts newest or most first, names and statuses A to Z). A cursor belongs to its order.
platformquerystringOptionalOnly launches on this ad platform (meta, or one from GET /platforms).
qquerystringOptionalSearch.
archivedquerystringOptionalInclude archived.
groupIdquerystringOptionalOnly the campaigns of this launch group (GET /launch-groups/{id}).
livenessquerystringOptionalOnly launches where they stand at their platform: in_progress (not published yet: drafts, scheduled, publishing, failed), live (published, and an ad is on with its ad set and campaign, or it spent in the last 7 days), not_live (published or imported, nothing on and no spend in 7 days), or active (in progress and live, the Launches page's default view). Left out: all.
afterquerystringOptionalCursor.
limitquerystringOptionalPage size.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].adAccountIdstring or null
act_…
items[].adCountinteger
Ads.
items[].adSetCountinteger
Ad sets.
items[].approvedCountinteger
Ads in a completed (approved) review status.
items[].archivedAtstring (date-time) or null
Archived.
items[].campaignIdstring or null
Existing campaign.
items[].createdAtstring (date-time)
Created.
items[].externalKeystring or null
Your own key.
items[].groupIdstring (uuid) or null
Its launch group.
items[].groupNamestring or null
Its launch group's own name.
items[].idstring (uuid)Required
ID.
items[].labelstring or null
Its own name in its launch group when a person gave one.
items[].livenessstring
Where it stands at its platform: not published yet, live (an ad is on, or it spent in the last 7 days), or not live.One of in_progress, live, not_live
items[].namestring
Name.
items[].newCampaignNamestring or null
The new campaign's name.
items[].platformstring
The ad platform it belongs to.
items[].previewMediaIdsarray of strings (uuid)
Processed media of the first four ads that have one, for thumbnails. Media still uploading or processing is left out.
items[].publishedAtstring (date-time) or null
First published.
items[].scheduleAtstring (date-time) or null
Start.
items[].statusstring
Status.
items[].updatedAtstring (date-time)
Last change.
items[].versioninteger
Increments on every change; send as expectedVersion.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/launches

Create a launch

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adAccountIdstring
The ad account it publishes to (Meta's: act_…).
campaignIdstring
Existing campaign.
campaignTemplateIdstring (uuid)
Start the new campaign from this campaign template (over the campaign defaults; keys in newCampaign still win).
externalKeystring
Your own key for this launch.
namestring
Name.
newCampaignobject
A campaign to create at publish, merged key by key over the launch's current new campaign (or a new one named after the launch). Choosing one replaces campaignId.
newCampaign.bidStrategystring
Bid strategy. LOWEST_COST_WITHOUT_CAP (Highest volume: Get the most results for your budget.) COST_CAP (Cost per result goal: Keep the average cost per result around a goal.) LOWEST_COST_WITH_BID_CAP (Bid cap: Set the most you'll bid in any auction.) LOWEST_COST_WITH_MIN_ROAS (ROAS goal: Keep return on ad spend above a goal. Requires value optimization.) Cost per result goals, bid caps and ROAS goals are set on each ad set (bidAmount, roasGoal); a ROAS goal needs the Sales objective.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
newCampaign.budgetstring
Campaign budget (budgetMode campaign) as a decimal string in the ad account's currency ("100", "99.50"). Never guessed: ask when unknown.
newCampaign.budgetModestring
campaign: one Advantage campaign budget shared across ad sets (CBO). ad_set: every ad set has its own budget (ABO).One of campaign, ad_set
newCampaign.budgetPeriodstring
With a campaign budget: daily, or lifetime (spent over the schedule; ad sets need an end).One of daily, lifetime
newCampaign.budgetSharingboolean
With ad set budgets: let ad sets share up to 20% of their budget with better-performing ad sets.
newCampaign.namestring
Campaign name, up to 400 characters.
newCampaign.objectivestring
Campaign objective: OUTCOME_AWARENESS (Awareness), OUTCOME_TRAFFIC (Traffic), OUTCOME_ENGAGEMENT (Engagement), OUTCOME_LEADS (Leads), OUTCOME_APP_PROMOTION (App promotion), OUTCOME_SALES (Sales).One of OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_APP_PROMOTION, OUTCOME_SALES
newCampaign.specialAdCategoriesarray of strings
Special ad categories, for ads about credit, jobs, housing, social issues or gambling: FINANCIAL_PRODUCTS_SERVICES (Financial products and services), EMPLOYMENT (Employment), HOUSING (Housing), ISSUES_ELECTIONS_POLITICS (Social issues, elections or politics), ONLINE_GAMBLING_AND_GAMING (Online gambling and gaming). Only a person declares them, in the app; the Agent never sets them.
newCampaign.specialAdCategoryCountryarray of strings
With a special ad category: the countries it applies in, as ISO 3166 codes (Meta's special_ad_category_country, Ads Manager's Countries under Special ad categories). Only a person declares them, in the app.
newCampaign.spendCapstring
Campaign spending limit (Ads Manager's), as a decimal string in the ad account's currency: the most the campaign spends over its life. Empty or absent for none. Meta sets its own minimum and refuses less.
platformstring
A platform from GET /platforms; fixed once created. Left out: the ad account's platform, else the one platform the workspace publishes to; with more than one connected (or several it may use and none connected) a 422 names the choice.
platformSettingsobject
A launch on a platform with its own launch settings (GET /platforms/{platform}/spec, content not null): {campaign: {…}, adSet: {…}} with that spec's fields. Not for Meta.
scheduleAtstring (date-time)
Start time.
settingsobject
Launch settings, patched key by key (get_meta_defaults shows the ad account's defaults); keys left out keep their value. Ad set defaults here (pixel, conversionEvent, audience, attribution, placements, delivery, beneficiary, payer) reach every ad set that doesn't set its own.
settings.adNamingstring
Ad name pattern: {{asset.name}}, {{campaign.name}}, {{index}}, {{date}} (the ad account's day) and text.
settings.adSetNamingstring
Ad set name pattern, like adNaming; "" names new ad sets "Ad set N".
settings.advantagePlacementsboolean
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
settings.audiencestring
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
settings.beneficiarystring
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
settings.catalogItemsboolean
Show products from your catalog (needs productSetId).
settings.clickAttributionstring
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
settings.conversionEventstring
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
settings.creativeobject
Advantage+ creative enhancements per format (each is opt-in).
settings.creative.carouselarray of strings
Carousel ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), profile_card (Profile end card), description_automation (Dynamic description).
settings.creative.imagearray of strings
Image ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), adapt_to_placement (Adapt to placement), image_touchups (Visual touch-ups), image_templates (Add overlays), image_brightness_and_contrast (Adjust brightness and contrast), image_animation (Image animation), image_background_gen (Generate backgrounds), image_uncrop (Expand image), music (Add music).
settings.creative.videoarray of strings
Video ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), video_auto_crop (Adjust aspect ratio), video_uncrop (Expand video), video_filtering (Video filters).
settings.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
settings.customConversionstring
One of the ad account's custom conversions to optimize for instead of a standard event: its numeric Meta ID (search_platform_targeting, platform meta, facet customConversions), with conversionEvent set to its event type. "" for none.
settings.deliverystring
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
settings.descriptionsarray of strings
Description. Keep one non-empty value.
settings.engagedAttributionstring
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
settings.headlinesarray of strings
Headline. Keep one non-empty value.
settings.instagramstring
Instagram account ads publish as: its Meta ID (get_meta_integration); usually the one linked to the Page. "" uses the Page.
settings.multiAdvertiserboolean
Multi-advertiser ads: the ad can appear alongside other businesses' ads.
settings.pagestring
Facebook Page ads publish as: its numeric Meta ID (get_meta_integration lists the Pages). The ad account must be able to publish as it.
settings.payerstring
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
settings.pixelstring
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
settings.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
settings.placementPositionsarray of strings
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
settings.placementsarray of strings
Manual placements: the platforms to show on (with advantagePlacements false).
settings.primaryTextsarray of strings
Primary text. Publishing sends one per ad: keep one non-empty value.
settings.productSetIdstring
Catalog product set: its numeric Meta ID.
settings.utmstring
URL parameters added to the link, like utm_source=facebook&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_content={{ad.name}} (Meta fills the {{…}} parameters).
settings.viewAttributionstring
View-through attribution window: "Off" or "1 day".One of Off, 1 day
settings.websiteUrlstring
Website URL ads link to (https://…).

Response201 Created

adAccountIdstring or null
act_…
archivedAtstring (date-time) or null
Archived.
campaignIdstring or null
The existing Meta campaign it publishes into; null when it creates newCampaign.
copiedFromLaunchIdstring (uuid) or null
The launch it was copied from to this platform.
createdAtstring (date-time)
Created.
externalKeystring or null
Your own key.
groupIdstring (uuid) or null
Its launch group (GET /launch-groups/{id}): the launch's other campaigns are there.
idstring (uuid)Required
ID.
invalidarray of objects
Only in a write's answer: values of the launch kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
invalid[].messagestringRequired
Problem.
labelstring or null
Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
namestring
Name.
newCampaignobject or null
The campaign it creates at publish.
newCampaign.bidStrategystring
Bid strategy.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
newCampaign.budgetstring
In the ad account currency; empty until set (a draft's new campaign starts without a budget unless the workspace's campaign defaults have one).
newCampaign.budgetModestring
campaign (Advantage campaign budget) or ad_set.One of campaign, ad_set
newCampaign.budgetPeriodstring
Period.One of daily, lifetime
newCampaign.budgetSharingboolean
Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.namestring
Name.
newCampaign.objectivestring
Meta objective.One of OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION
newCampaign.specialAdCategoriesarray of strings
Special ad categories.
newCampaign.spendCapstring
Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
platformstring
The ad platform it belongs to (meta, or a platform from GET /platforms); fixed at creation.
platformSettingsobject or null
The platform's own launch settings (GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta.
publishJobIdstring (uuid) or null
The latest publish job.
publishedAtstring (date-time) or null
First published.
scheduleAtstring (date-time) or null
When publishing starts.
settingsobject
The launch's settings its ad sets and ads inherit. Meta: all of them. Another platform: only the content every platform shares (primaryTexts, headlines, descriptions, cta, websiteUrl, utm, adNaming, adSetNaming, delivery); its own settings are platformSettings.
sharedWithGuestsboolean
Shared with the workspace's guests for review.
statusstring
Status.One of draft, publishing, published, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: f16914b2-b0c6-4111-b6b5-bd519fcc7f9f" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_741877585619437",
    "campaignId": "120227168091908311",
    "campaignTemplateId": "6129091c-83d6-4258-85bf-32848492839d",
    "externalKey": "fall-2026-launch",
    "name": "Fall launch",
    "newCampaign": {
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": "150.00",
      "budgetMode": "campaign",
      "budgetPeriod": "daily",
      "budgetSharing": true,
      "name": "Daily budget",
      "objective": "OUTCOME_AWARENESS",
      "specialAdCategories": [
        "FINANCIAL_PRODUCTS_SERVICES"
      ],
      "specialAdCategoryCountry": [],
      "spendCap": "25.00"
    },
    "platform": "422",
    "platformSettings": {},
    "scheduleAt": "2026-09-30T13:00:00Z",
    "settings": {
      "adNaming": "2026-09-27",
      "adSetNaming": "Brevanne",
      "advantagePlacements": true,
      "audience": "Advantage+ audience",
      "beneficiary": "Brevanne, Inc.",
      "catalogItems": true,
      "clickAttribution": "1 day",
      "conversionEvent": "PURCHASE",
      "creative": {
        "carousel": [
          "text_optimizations"
        ],
        "image": [
          "text_optimizations"
        ],
        "video": [
          "text_optimizations"
        ]
      },
      "cta": "Apply now",
      "customConversion": "1",
      "delivery": "Paused",
      "descriptions": [
        "Two drops every morning for brighter, even skin."
      ],
      "engagedAttribution": "Off",
      "headlines": [
        "Brighter skin in 14 days"
      ],
      "instagram": "Brevanne",
      "multiAdvertiser": true,
      "page": "Brevanne",
      "payer": "Brevanne, Inc.",
      "pixel": "Brevanne",
      "placementCrops": "off",
      "placementPositions": [
        "facebook.feed"
      ],
      "placements": [
        "Facebook"
      ],
      "primaryTexts": [
        "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50."
      ],
      "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd",
      "utm": "https://brevanne.com/products/vitamin-c-serum",
      "viewAttribution": "Off",
      "websiteUrl": "https://brevanne.com/products/vitamin-c-serum"
    }
  }'
POST/launches/batch

Create launches in bulk

Each item carries its own commandId (an idempotency key for that item, interchangeable with the Idempotency-Key of POST /launches) and gets its own outcome; a bad item never fails the others. 1 to 1000 items. Flat launches only: a launch with its ad sets and ads in one document is a launch spec (/launches/specs/apply).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

itemsarray of objectsRequired
Launches.
items[].adAccountIdstring
act_…
items[].campaignIdstring
Existing campaign.
items[].commandIdstringRequired
This item's command ID.
items[].externalKeystring
Your own key for this launch.
items[].namestring
Name.
items[].newCampaignobject
A campaign to create at publish, merged key by key over the launch's current new campaign (or a new one named after the launch). Choosing one replaces campaignId.
items[].newCampaign.bidStrategystring
Bid strategy. LOWEST_COST_WITHOUT_CAP (Highest volume: Get the most results for your budget.) COST_CAP (Cost per result goal: Keep the average cost per result around a goal.) LOWEST_COST_WITH_BID_CAP (Bid cap: Set the most you'll bid in any auction.) LOWEST_COST_WITH_MIN_ROAS (ROAS goal: Keep return on ad spend above a goal. Requires value optimization.) Cost per result goals, bid caps and ROAS goals are set on each ad set (bidAmount, roasGoal); a ROAS goal needs the Sales objective.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
items[].newCampaign.budgetstring
Campaign budget (budgetMode campaign) as a decimal string in the ad account's currency ("100", "99.50"). Never guessed: ask when unknown.
items[].newCampaign.budgetModestring
campaign: one Advantage campaign budget shared across ad sets (CBO). ad_set: every ad set has its own budget (ABO).One of campaign, ad_set
items[].newCampaign.budgetPeriodstring
With a campaign budget: daily, or lifetime (spent over the schedule; ad sets need an end).One of daily, lifetime
items[].newCampaign.budgetSharingboolean
With ad set budgets: let ad sets share up to 20% of their budget with better-performing ad sets.
items[].newCampaign.namestring
Campaign name, up to 400 characters.
items[].newCampaign.objectivestring
Campaign objective: OUTCOME_AWARENESS (Awareness), OUTCOME_TRAFFIC (Traffic), OUTCOME_ENGAGEMENT (Engagement), OUTCOME_LEADS (Leads), OUTCOME_APP_PROMOTION (App promotion), OUTCOME_SALES (Sales).One of OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_APP_PROMOTION, OUTCOME_SALES
items[].newCampaign.specialAdCategoriesarray of strings
Special ad categories, for ads about credit, jobs, housing, social issues or gambling: FINANCIAL_PRODUCTS_SERVICES (Financial products and services), EMPLOYMENT (Employment), HOUSING (Housing), ISSUES_ELECTIONS_POLITICS (Social issues, elections or politics), ONLINE_GAMBLING_AND_GAMING (Online gambling and gaming). Only a person declares them, in the app; the Agent never sets them.
items[].newCampaign.specialAdCategoryCountryarray of strings
With a special ad category: the countries it applies in, as ISO 3166 codes (Meta's special_ad_category_country, Ads Manager's Countries under Special ad categories). Only a person declares them, in the app.
items[].newCampaign.spendCapstring
Campaign spending limit (Ads Manager's), as a decimal string in the ad account's currency: the most the campaign spends over its life. Empty or absent for none. Meta sets its own minimum and refuses less.
items[].platformstring
A platform from GET /platforms; left out, as for POST /launches.
items[].platformSettingsobject
The platform's own launch settings (not for Meta).
items[].scheduleAtstring (date-time)
Start time.
items[].settingsobject
Launch settings, patched key by key (get_meta_defaults shows the ad account's defaults); keys left out keep their value. Ad set defaults here (pixel, conversionEvent, audience, attribution, placements, delivery, beneficiary, payer) reach every ad set that doesn't set its own.
items[].settings.adNamingstring
Ad name pattern: {{asset.name}}, {{campaign.name}}, {{index}}, {{date}} (the ad account's day) and text.
items[].settings.adSetNamingstring
Ad set name pattern, like adNaming; "" names new ad sets "Ad set N".
items[].settings.advantagePlacementsboolean
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
items[].settings.audiencestring
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
items[].settings.beneficiarystring
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].settings.catalogItemsboolean
Show products from your catalog (needs productSetId).
items[].settings.clickAttributionstring
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
items[].settings.conversionEventstring
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
items[].settings.creativeobject
Advantage+ creative enhancements per format (each is opt-in).
items[].settings.creative.carouselarray of strings
Carousel ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), profile_card (Profile end card), description_automation (Dynamic description).
items[].settings.creative.imagearray of strings
Image ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), adapt_to_placement (Adapt to placement), image_touchups (Visual touch-ups), image_templates (Add overlays), image_brightness_and_contrast (Adjust brightness and contrast), image_animation (Image animation), image_background_gen (Generate backgrounds), image_uncrop (Expand image), music (Add music).
items[].settings.creative.videoarray of strings
Video ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), video_auto_crop (Adjust aspect ratio), video_uncrop (Expand video), video_filtering (Video filters).
items[].settings.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
items[].settings.customConversionstring
One of the ad account's custom conversions to optimize for instead of a standard event: its numeric Meta ID (search_platform_targeting, platform meta, facet customConversions), with conversionEvent set to its event type. "" for none.
items[].settings.deliverystring
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
items[].settings.descriptionsarray of strings
Description. Keep one non-empty value.
items[].settings.engagedAttributionstring
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
items[].settings.headlinesarray of strings
Headline. Keep one non-empty value.
items[].settings.instagramstring
Instagram account ads publish as: its Meta ID (get_meta_integration); usually the one linked to the Page. "" uses the Page.
items[].settings.multiAdvertiserboolean
Multi-advertiser ads: the ad can appear alongside other businesses' ads.
items[].settings.pagestring
Facebook Page ads publish as: its numeric Meta ID (get_meta_integration lists the Pages). The ad account must be able to publish as it.
items[].settings.payerstring
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].settings.pixelstring
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].settings.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
items[].settings.placementPositionsarray of strings
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
items[].settings.placementsarray of strings
Manual placements: the platforms to show on (with advantagePlacements false).
items[].settings.primaryTextsarray of strings
Primary text. Publishing sends one per ad: keep one non-empty value.
items[].settings.productSetIdstring
Catalog product set: its numeric Meta ID.
items[].settings.utmstring
URL parameters added to the link, like utm_source=facebook&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_content={{ad.name}} (Meta fills the {{…}} parameters).
items[].settings.viewAttributionstring
View-through attribution window: "Off" or "1 day".One of Off, 1 day
items[].settings.websiteUrlstring
Website URL ads link to (https://…).

Response200 OK

itemsarray of objectsRequired
One outcome per item, in order: launch when accepted; errors when rejected (a commandId reused for other input is rejected on commandId); message on a conflict.
items[].commandIdstringRequired
The item's command ID.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].launchobject
A launch: one batch of ads for a provider ad account.
items[].launch.adAccountIdstring or null
act_…
items[].launch.archivedAtstring (date-time) or null
Archived.
items[].launch.campaignIdstring or null
The existing Meta campaign it publishes into; null when it creates newCampaign.
items[].launch.copiedFromLaunchIdstring (uuid) or null
The launch it was copied from to this platform.
items[].launch.createdAtstring (date-time)
Created.
items[].launch.externalKeystring or null
Your own key.
items[].launch.groupIdstring (uuid) or null
Its launch group (GET /launch-groups/{id}): the launch's other campaigns are there.
items[].launch.idstring (uuid)Required
ID.
items[].launch.invalidarray of objects
Only in a write's answer: values of the launch kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
items[].launch.invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
items[].launch.invalid[].messagestringRequired
Problem.
items[].launch.labelstring or null
Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
items[].launch.namestring
Name.
items[].launch.newCampaignobject or null
The campaign it creates at publish.
items[].launch.newCampaign.bidStrategystring
Bid strategy.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
items[].launch.newCampaign.budgetstring
In the ad account currency; empty until set (a draft's new campaign starts without a budget unless the workspace's campaign defaults have one).
items[].launch.newCampaign.budgetModestring
campaign (Advantage campaign budget) or ad_set.One of campaign, ad_set
items[].launch.newCampaign.budgetPeriodstring
Period.One of daily, lifetime
items[].launch.newCampaign.budgetSharingboolean
Ad sets share up to 20% of their budget (ad set budgets only).
items[].launch.newCampaign.namestring
Name.
items[].launch.newCampaign.objectivestring
Meta objective.One of OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION
items[].launch.newCampaign.specialAdCategoriesarray of strings
Special ad categories.
items[].launch.newCampaign.spendCapstring
Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
items[].launch.platformstring
The ad platform it belongs to (meta, or a platform from GET /platforms); fixed at creation.
items[].launch.platformSettingsobject or null
The platform's own launch settings (GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta.
items[].launch.publishJobIdstring (uuid) or null
The latest publish job.
items[].launch.publishedAtstring (date-time) or null
First published.
items[].launch.scheduleAtstring (date-time) or null
When publishing starts.
items[].launch.settingsobject
The launch's settings its ad sets and ads inherit. Meta: all of them. Another platform: only the content every platform shares (primaryTexts, headlines, descriptions, cta, websiteUrl, utm, adNaming, adSetNaming, delivery); its own settings are platformSettings.
items[].launch.sharedWithGuestsboolean
Shared with the workspace's guests for review.
items[].launch.statusstring
Status.One of draft, publishing, published, failed
items[].launch.updatedAtstring (date-time)
Last change.
items[].launch.versioninteger
Increments on every change; send as expectedVersion.
items[].messagestring
Why it conflicts.
items[].messageCodestring
A registered message's stable code (such as ad_exists_in_launch), for an app to say it in its language.
items[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].statusstringRequired
Outcome of this item.One of accepted, rejected, conflict

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/batch" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: aba4efbf-3de5-4e0f-a70e-29e3ac6a5d9b" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "adAccountId": "act_741877585619437",
        "campaignId": "120227168091908311",
        "commandId": "ca4b1318-93a6-403c-9e0c-0e2ff51907bd",
        "externalKey": "fall-2026-launch",
        "name": "Vitamin C Serum",
        "newCampaign": {
          "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
          "budget": "150.00",
          "budgetMode": "campaign",
          "budgetPeriod": "daily",
          "budgetSharing": true,
          "name": "Daily budget",
          "objective": "OUTCOME_AWARENESS",
          "specialAdCategories": [
            "FINANCIAL_PRODUCTS_SERVICES"
          ],
          "specialAdCategoryCountry": [],
          "spendCap": "25.00"
        },
        "platform": "Brevanne",
        "platformSettings": {},
        "scheduleAt": "2026-09-30T13:00:00Z",
        "settings": {
          "adNaming": "2026-09-27",
          "adSetNaming": "Brevanne",
          "advantagePlacements": true,
          "audience": "Advantage+ audience",
          "beneficiary": "Brevanne, Inc.",
          "catalogItems": true,
          "clickAttribution": "1 day",
          "conversionEvent": "PURCHASE",
          "creative": {
            "carousel": [
              "text_optimizations"
            ],
            "image": [
              "text_optimizations"
            ],
            "video": [
              "text_optimizations"
            ]
          },
          "cta": "Apply now",
          "customConversion": "1",
          "delivery": "Paused",
          "descriptions": [
            "Two drops every morning for brighter, even skin."
          ],
          "engagedAttribution": "Off",
          "headlines": [
            "Brighter skin in 14 days"
          ],
          "instagram": "Brevanne",
          "multiAdvertiser": true,
          "page": "Brevanne",
          "payer": "Brevanne, Inc.",
          "pixel": "Brevanne",
          "placementCrops": "off",
          "placementPositions": [
            "facebook.feed"
          ],
          "placements": [
            "Facebook"
          ],
          "primaryTexts": [
            "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50."
          ],
          "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd",
          "utm": "https://brevanne.com/products/vitamin-c-serum",
          "viewAttribution": "Off",
          "websiteUrl": "https://brevanne.com/products/vitamin-c-serum"
        }
      }
    ]
  }'
GET/launches/liveness

List inactive launches

The launches not archived that are published or imported but not live at their platform: no ad of them on with its ad set and campaign, and no spend in the last 7 days. Read from the platform's statuses as synced and the imported insights every few minutes; a launch not read yet counts as live. Every other launch not archived is in progress or live (liveness on GET /launches).

Permission: readGuests too

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

notLivearray of strings (uuid)Required
Launches not archived that are published or imported and not live.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/liveness" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/launches/specs/apply

Apply a launch spec

JSON, or NDJSON (application/x-ndjson) for large specs. Applies the difference against current state as one command. Up to 200 ad sets and ads apply at once (200); larger specs apply the launch, then queue the ad sets and ads as a job (202 with jobId; per-item outcomes in the job's items).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adAccountIdstring
act_…
adSetsarray of objects
Ad sets.
adSets[].externalKeystringRequired
Your key.
adSets[].namestringRequired
Name.
adSets[].overridesobject
Launch settings this ad set changes.
adSets[].targetingobject
Targeting (may include metaSettings).
adsarray of objects
Ads.
ads[].adSetstring
The ad set's externalKey; absent is ungrouped.
ads[].externalKeystringRequired
Your key.
ads[].mediaIdstring (uuid)Required
The creative: an image or a video.
ads[].namestring
Defaults to the launch's naming pattern.
ads[].overridesobject
What the ad changes.
campaignIdstring
An existing campaign to publish into.
externalKeystringRequired
Your key for the launch; applying again updates it.
namestringRequired
Name.
newCampaignobject
newCampaign.bidStrategystring
Bid strategy.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
newCampaign.budgetstring
In the ad account currency; empty until set (a draft's new campaign starts without a budget unless the workspace's campaign defaults have one).
newCampaign.budgetModestring
campaign (Advantage campaign budget) or ad_set.One of campaign, ad_set
newCampaign.budgetPeriodstring
Period.One of daily, lifetime
newCampaign.budgetSharingboolean
Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.namestring
Name.
newCampaign.objectivestring
Meta objective.One of OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION
newCampaign.specialAdCategoriesarray of strings
Special ad categories.
newCampaign.spendCapstring
Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
scheduleAtstring (date-time)
Start.
settingsobject
Settings over the workspace/account defaults on creation, over the current settings on update.

Response200 OK

The launch and what was created or updated.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/specs/apply" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 37116427-8222-4049-bd46-14f63dc13198" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_741877585619437",
    "adSets": [
      {
        "externalKey": "fall-2026-launch",
        "name": "Broad, United States",
        "overrides": {},
        "targeting": {}
      }
    ],
    "ads": [
      {
        "adSet": "Broad, United States",
        "externalKey": "fall-2026-launch",
        "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
        "name": "Vitamin C Serum, UGC 9x16",
        "overrides": {}
      }
    ],
    "campaignId": "120227168091908311",
    "externalKey": "fall-2026-launch",
    "name": "Fall launch",
    "newCampaign": {
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": "150.00",
      "budgetMode": "campaign",
      "budgetPeriod": "daily",
      "budgetSharing": true,
      "name": "Daily budget",
      "objective": "OUTCOME_SALES",
      "specialAdCategories": [],
      "spendCap": "25.00"
    },
    "scheduleAt": "2026-09-30T13:00:00Z",
    "settings": {}
  }'
POST/launches/specs/validate

Validate a launch spec (dry run)

Permission: write

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adAccountIdstring
act_…
adSetsarray of objects
Ad sets.
adSets[].externalKeystringRequired
Your key.
adSets[].namestringRequired
Name.
adSets[].overridesobject
Launch settings this ad set changes.
adSets[].targetingobject
Targeting (may include metaSettings).
adsarray of objects
Ads.
ads[].adSetstring
The ad set's externalKey; absent is ungrouped.
ads[].externalKeystringRequired
Your key.
ads[].mediaIdstring (uuid)Required
The creative: an image or a video.
ads[].namestring
Defaults to the launch's naming pattern.
ads[].overridesobject
What the ad changes.
campaignIdstring
An existing campaign to publish into.
externalKeystringRequired
Your key for the launch; applying again updates it.
namestringRequired
Name.
newCampaignobject
newCampaign.bidStrategystring
Bid strategy.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
newCampaign.budgetstring
In the ad account currency; empty until set (a draft's new campaign starts without a budget unless the workspace's campaign defaults have one).
newCampaign.budgetModestring
campaign (Advantage campaign budget) or ad_set.One of campaign, ad_set
newCampaign.budgetPeriodstring
Period.One of daily, lifetime
newCampaign.budgetSharingboolean
Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.namestring
Name.
newCampaign.objectivestring
Meta objective.One of OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION
newCampaign.specialAdCategoriesarray of strings
Special ad categories.
newCampaign.spendCapstring
Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
scheduleAtstring (date-time)
Start.
settingsobject
Settings over the workspace/account defaults on creation, over the current settings on update.

Response200 OK

valid, every error, and the plan (created/updated per level).

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/specs/validate" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_741877585619437",
    "adSets": [
      {
        "externalKey": "fall-2026-launch",
        "name": "Broad, United States",
        "overrides": {},
        "targeting": {}
      }
    ],
    "ads": [
      {
        "adSet": "Broad, United States",
        "externalKey": "fall-2026-launch",
        "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
        "name": "Vitamin C Serum, UGC 9x16",
        "overrides": {}
      }
    ],
    "campaignId": "120227168091908311",
    "externalKey": "fall-2026-launch",
    "name": "Fall launch",
    "newCampaign": {
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": "150.00",
      "budgetMode": "campaign",
      "budgetPeriod": "daily",
      "budgetSharing": true,
      "name": "Daily budget",
      "objective": "OUTCOME_SALES",
      "specialAdCategories": [],
      "spendCap": "25.00"
    },
    "scheduleAt": "2026-09-30T13:00:00Z",
    "settings": {}
  }'
GET/launches/stats

Count launches

Open and published launches, counted as the Launches list shows them: one per launch, published when every active campaign is, open otherwise (partly published included). Ads in review or with changes requested in unpublished campaigns, and the caller's assigned review work.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

archivedintegerRequired
Archived launches, a launch with several campaigns once.
assignedarray of objectsRequired
The caller's ads in review or with changes requested (at most 50).
assigned[].adIdstring (uuid)Required
Ad.
assigned[].adNamestringRequired
Name.
assigned[].launchIdstring (uuid)Required
Launch.
assigned[].launchNamestringRequired
Launch name.
assigned[].mediaIdstring (uuid) or null
Creative.
assigned[].statusIdstring (uuid) or null
Review status.
changesRequestedintegerRequired
Ads with changes requested.
inReviewintegerRequired
Ads in review.
openintegerRequired
Launches not published.
publishedintegerRequired
Published launches.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/stats" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/launches/{id}

Get a launch

The launch with its ad sets and ads, overrides and effective values. Guests get it without the publishing checklist: review has no items and ready is false.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accountobject or null
The ad account as synced from Meta: id, name, currency, timezone.
adSetsarray of objectsRequired
Ad sets in order.
adSets[].effectiveobject
The launch settings with the overrides on top.
adSets[].externalKeystring or null
Your own key.
adSets[].idstring (uuid)Required
ID.
adSets[].invalidarray of objects
Only in a write's answer: values of the ad set (its own or the launch's it inherits) kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
adSets[].invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
adSets[].invalid[].messagestringRequired
Problem.
adSets[].launchIdstring (uuid)
Launch.
adSets[].namestring
Name.
adSets[].overridesobject
Only the launch settings this ad set changes.
adSets[].platformSettingsobject
A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's ({} for Meta).
adSets[].positioninteger
Order.
adSets[].targetingobject
The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
adSets[].versioninteger
Increments on every change; send as expectedVersion.
adsarray of objectsRequired
Ads in order.
ads[].adSetIdstring (uuid) or null
Ad set; null is ungrouped.
ads[].assigneeIdstring (uuid) or null
Assignee.
ads[].createdAtstring (date-time)
Created.
ads[].creativeLinkIdstring (uuid) or null
Shared with the ads copied from or to it in its launch group's other campaigns (GET /ads/{id}/linked).
ads[].cropsobject
Meta: an image ad that crops for each placement, the box of each shape it publishes with (1:1, 4:5, 9:16, 1.91:1), in its image's pixels: its own, else the middle. Absent when it doesn't crop or its image isn't measured yet.
ads[].effectiveobject
The content the ad publishes: overrides, otherwise the launch's values.
ads[].externalKeystring or null
Your own key.
ads[].formatstring
Creative format: audio is an audio ad, where the platform has them; text is an ad with no file, no cards and no existing post (an X text Post, a Google or Microsoft search ad, a Reddit free-form ad; where the platform's ads need a file, it is still to come).One of image, video, carousel, audio, text
ads[].idstring (uuid)Required
ID.
ads[].issuesarray of strings
Problems with the effective content.
ads[].labelIdsarray of strings (uuid)
Labels.
ads[].launchIdstring (uuid)
Launch.
ads[].mediaIdstring (uuid) or null
Creative.
ads[].namestring
Name.
ads[].overridesobject
Only what this ad changes.
ads[].positioninteger
Order.
ads[].statusIdstring (uuid) or null
Review status.
ads[].updatedAtstring (date-time)
Last change.
ads[].versioninteger
Increments on every change; send as expectedVersion.
campaignobject or null
The existing campaign it publishes into, as synced: id, name, objective, status, bidStrategy, budgetMode, dailyBudget, lifetimeBudget (decimal strings or null).
campaignNamestringRequired
The Meta campaign name ads are named with.
canDeletebooleanRequired
Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
createPathstring
On a platform whose create path depends on the ad account: smart_plus (its automated campaign type) or manual, how the launch's new campaign is created. Absent when the platform creates no such campaign now (the checklist says why), when publishing into an existing campaign, and on platforms with one create path.
launchobjectRequired
A launch: one batch of ads for a provider ad account.
launch.adAccountIdstring or null
act_…
launch.archivedAtstring (date-time) or null
Archived.
launch.campaignIdstring or null
The existing Meta campaign it publishes into; null when it creates newCampaign.
launch.copiedFromLaunchIdstring (uuid) or null
The launch it was copied from to this platform.
launch.createdAtstring (date-time)
Created.
launch.externalKeystring or null
Your own key.
launch.groupIdstring (uuid) or null
Its launch group (GET /launch-groups/{id}): the launch's other campaigns are there.
launch.idstring (uuid)Required
ID.
launch.invalidarray of objects
Only in a write's answer: values of the launch kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
launch.invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
launch.invalid[].messagestringRequired
Problem.
launch.labelstring or null
Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
launch.namestring
Name.
launch.newCampaignobject or null
The campaign it creates at publish.
launch.newCampaign.bidStrategystring
Bid strategy.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
launch.newCampaign.budgetstring
In the ad account currency; empty until set (a draft's new campaign starts without a budget unless the workspace's campaign defaults have one).
launch.newCampaign.budgetModestring
campaign (Advantage campaign budget) or ad_set.One of campaign, ad_set
launch.newCampaign.budgetPeriodstring
Period.One of daily, lifetime
launch.newCampaign.budgetSharingboolean
Ad sets share up to 20% of their budget (ad set budgets only).
launch.newCampaign.namestring
Name.
launch.newCampaign.objectivestring
Meta objective.One of OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION
launch.newCampaign.specialAdCategoriesarray of strings
Special ad categories.
launch.newCampaign.spendCapstring
Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
launch.platformstring
The ad platform it belongs to (meta, or a platform from GET /platforms); fixed at creation.
launch.platformSettingsobject or null
The platform's own launch settings (GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta.
launch.publishJobIdstring (uuid) or null
The latest publish job.
launch.publishedAtstring (date-time) or null
First published.
launch.scheduleAtstring (date-time) or null
When publishing starts.
launch.settingsobject
The launch's settings its ad sets and ads inherit. Meta: all of them. Another platform: only the content every platform shares (primaryTexts, headlines, descriptions, cta, websiteUrl, utm, adNaming, adSetNaming, delivery); its own settings are platformSettings.
launch.sharedWithGuestsboolean
Shared with the workspace's guests for review.
launch.statusstring
Status.One of draft, publishing, published, failed
launch.updatedAtstring (date-time)
Last change.
launch.versioninteger
Increments on every change; send as expectedVersion.
reviewobjectRequired
review.excludedobjectRequired
review.excluded.emptyAdSetsarray of objectsRequired
Ad sets without creatives. Meta delivers only through ads, so they aren't created (nor their budget approved) until they have one.
review.excluded.emptyAdSets[].idstring (uuid)Required
Ad set.
review.excluded.emptyAdSets[].namestringRequired
Name.
review.excluded.ungroupedAdIdsarray of strings (uuid)Required
Their IDs, in board order.
review.excluded.ungroupedAdsintegerRequired
Creatives in Ungrouped. They are drafts: not published, not counted in creates or the budget, and their gaps don't block publishing.
review.itemsarray of objectsRequired
What still blocks publishing: only ad sets with creatives and the ads in them are checked.
review.items[].actionstring
A one-step fix: split_ad_set runs POST /ad-sets/{id}/split on adSetId.
review.items[].adIdstring
The ad it concerns.
review.items[].adNamestring
Its name.
review.items[].adSetstring
The ad set it concerns, by name.
review.items[].adSetIdstring
The ad set's ID.
review.items[].fieldstringRequired
Where the person fixes it, as the app names the place (Ad account, Campaign, Headline, Ad set settings, Ad sets, Launch settings): a label to show, the same kind on every platform. Never a path; match, focus or route on path.
review.items[].idstringRequired
Stable item ID.
review.items[].labelstringRequired
Short label.
review.items[].labelCodestring
A registered label's stable code (such as review_match_campaign_objective), for an app to say it in its language; absent when the label is free text.
review.items[].labelParamsobject
The values labelCode's sentence names, present exactly when it names any.
review.items[].labelPlaceobject
The one text a coded label is said of, apart from its sentence so an app says both in its language: { field (headline, description, keyword or negativeKeyword), index (1-based) } (a platform's check on an ad's third headline: headline, 3). Absent when the label names no place or holds it as free text; label keeps it in English.
review.items[].messagestringRequired
What to fix.
review.items[].nextCodestring
The next step's stable code when message is a registered next step (a platform's own check), for an app to say it under the label in its language; absent otherwise.
review.items[].nextParamsobject
The values nextCode's sentence names, present exactly when it names any.
review.items[].nextTopicsstring
The policy topics the platform names beside the next step, in its own words (TRADEMARKS, ALCOHOL), present with nextCode when it names any.
review.items[].pathstring or nullRequired
The API path of the value to fix, on every platform: on the launch (adAccountId, settings.page, newCampaign.budget, platformSettings.campaign.objective), the ad set in adSetId (targeting.countries, overrides.beneficiary, platformSettings.costType) or the ad in adId (overrides.url), as in publishing errors' field. What to match, focus or route on. Null when the fix isn't a field: connect Meta, add creatives, or move creatives into an ad set.
review.readybooleanRequired
No checklist items remain.
smartPlusAccessobject
smartPlusAccess.learnedAtstring (date-time) or nullRequired
When Pluto learned it.
smartPlusAccess.manualUntilstringRequired
The last day the platform creates manual campaigns (a date).
smartPlusAccess.statusstringRequired
yes, no or unknown (not tried yet).

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/launches/{id}

Update a launch

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adAccountIdstring
act_…
campaignIdstring
Campaign.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
labelstring
Its own name in its launch group (GET /launch-groups/{id}), e.g. Leads. Its full name follows while it follows the campaign naming rule and never published.
namestring
Name.
newCampaignobject or null
The campaign the launch creates at publish, instead of campaignId: merged key by key over the current one (or a new one named after the launch); null stops creating one. Values the editor never saves (a budget that isn't an amount, a ROAS goal without Sales) are a 422.
newCampaign.bidStrategystring
Bid strategy. LOWEST_COST_WITHOUT_CAP (Highest volume: Get the most results for your budget.) COST_CAP (Cost per result goal: Keep the average cost per result around a goal.) LOWEST_COST_WITH_BID_CAP (Bid cap: Set the most you'll bid in any auction.) LOWEST_COST_WITH_MIN_ROAS (ROAS goal: Keep return on ad spend above a goal. Requires value optimization.) Cost per result goals, bid caps and ROAS goals are set on each ad set (bidAmount, roasGoal); a ROAS goal needs the Sales objective.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
newCampaign.budgetstring
Campaign budget (budgetMode campaign) as a decimal string in the ad account's currency ("100", "99.50"). Never guessed: ask when unknown.
newCampaign.budgetModestring
campaign: one Advantage campaign budget shared across ad sets (CBO). ad_set: every ad set has its own budget (ABO).One of campaign, ad_set
newCampaign.budgetPeriodstring
With a campaign budget: daily, or lifetime (spent over the schedule; ad sets need an end).One of daily, lifetime
newCampaign.budgetSharingboolean
With ad set budgets: let ad sets share up to 20% of their budget with better-performing ad sets.
newCampaign.namestring
Campaign name, up to 400 characters.
newCampaign.objectivestring
Campaign objective: OUTCOME_AWARENESS (Awareness), OUTCOME_TRAFFIC (Traffic), OUTCOME_ENGAGEMENT (Engagement), OUTCOME_LEADS (Leads), OUTCOME_APP_PROMOTION (App promotion), OUTCOME_SALES (Sales).One of OUTCOME_AWARENESS, OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_APP_PROMOTION, OUTCOME_SALES
newCampaign.specialAdCategoriesarray of strings
Special ad categories, for ads about credit, jobs, housing, social issues or gambling: FINANCIAL_PRODUCTS_SERVICES (Financial products and services), EMPLOYMENT (Employment), HOUSING (Housing), ISSUES_ELECTIONS_POLITICS (Social issues, elections or politics), ONLINE_GAMBLING_AND_GAMING (Online gambling and gaming). Only a person declares them, in the app; the Agent never sets them.
newCampaign.specialAdCategoryCountryarray of strings
With a special ad category: the countries it applies in, as ISO 3166 codes (Meta's special_ad_category_country, Ads Manager's Countries under Special ad categories). Only a person declares them, in the app.
newCampaign.spendCapstring
Campaign spending limit (Ads Manager's), as a decimal string in the ad account's currency: the most the campaign spends over its life. Empty or absent for none. Meta sets its own minimum and refuses less.
platformstring
Moves a draft that never published to another platform from GET /platforms, sent with adAccountId there and nothing else. Copy, link, media, ad sets and ads stay; that platform's own settings (campaign, ad sets, buttons) come back as they were when the draft was last there, otherwise they start from its defaults. Refused (422) once anything is published: duplicate to the platform instead.
platformSettingsobject
A launch on a platform with its own launch settings: {campaign: {…}, adSet: {…}}, each named key replacing its value.
scheduleAtstring (date-time)
Start.
settingsobject
Launch settings, patched key by key (get_meta_defaults shows the ad account's defaults); keys left out keep their value. Ad set defaults here (pixel, conversionEvent, audience, attribution, placements, delivery, beneficiary, payer) reach every ad set that doesn't set its own.
settings.adNamingstring
Ad name pattern: {{asset.name}}, {{campaign.name}}, {{index}}, {{date}} (the ad account's day) and text.
settings.adSetNamingstring
Ad set name pattern, like adNaming; "" names new ad sets "Ad set N".
settings.advantagePlacementsboolean
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
settings.audiencestring
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
settings.beneficiarystring
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
settings.catalogItemsboolean
Show products from your catalog (needs productSetId).
settings.clickAttributionstring
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
settings.conversionEventstring
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
settings.creativeobject
Advantage+ creative enhancements per format (each is opt-in).
settings.creative.carouselarray of strings
Carousel ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), profile_card (Profile end card), description_automation (Dynamic description).
settings.creative.imagearray of strings
Image ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), adapt_to_placement (Adapt to placement), image_touchups (Visual touch-ups), image_templates (Add overlays), image_brightness_and_contrast (Adjust brightness and contrast), image_animation (Image animation), image_background_gen (Generate backgrounds), image_uncrop (Expand image), music (Add music).
settings.creative.videoarray of strings
Video ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), video_auto_crop (Adjust aspect ratio), video_uncrop (Expand video), video_filtering (Video filters).
settings.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
settings.customConversionstring
One of the ad account's custom conversions to optimize for instead of a standard event: its numeric Meta ID (search_platform_targeting, platform meta, facet customConversions), with conversionEvent set to its event type. "" for none.
settings.deliverystring
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
settings.descriptionsarray of strings
Description. Keep one non-empty value.
settings.engagedAttributionstring
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
settings.headlinesarray of strings
Headline. Keep one non-empty value.
settings.instagramstring
Instagram account ads publish as: its Meta ID (get_meta_integration); usually the one linked to the Page. "" uses the Page.
settings.multiAdvertiserboolean
Multi-advertiser ads: the ad can appear alongside other businesses' ads.
settings.pagestring
Facebook Page ads publish as: its numeric Meta ID (get_meta_integration lists the Pages). The ad account must be able to publish as it.
settings.payerstring
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
settings.pixelstring
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
settings.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
settings.placementPositionsarray of strings
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
settings.placementsarray of strings
Manual placements: the platforms to show on (with advantagePlacements false).
settings.primaryTextsarray of strings
Primary text. Publishing sends one per ad: keep one non-empty value.
settings.productSetIdstring
Catalog product set: its numeric Meta ID.
settings.utmstring
URL parameters added to the link, like utm_source=facebook&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_content={{ad.name}} (Meta fills the {{…}} parameters).
settings.viewAttributionstring
View-through attribution window: "Off" or "1 day".One of Off, 1 day
settings.websiteUrlstring
Website URL ads link to (https://…).
sharedWithGuestsboolean
Share the launch with the workspace's guests for review (they read it and everything in it: ad sets, ads, creatives, activity and comments), or stop. Guests see no other launch. A new launch starts as the workspace's shareNewLaunchesWithGuests says (off by default). Assigning an ad to a guest or mentioning one in a comment shares it too.

Response200 OK

adAccountIdstring or null
act_…
archivedAtstring (date-time) or null
Archived.
campaignIdstring or null
The existing Meta campaign it publishes into; null when it creates newCampaign.
copiedFromLaunchIdstring (uuid) or null
The launch it was copied from to this platform.
createdAtstring (date-time)
Created.
externalKeystring or null
Your own key.
groupIdstring (uuid) or null
Its launch group (GET /launch-groups/{id}): the launch's other campaigns are there.
idstring (uuid)Required
ID.
invalidarray of objects
Only in a write's answer: values of the launch kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
invalid[].messagestringRequired
Problem.
labelstring or null
Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
namestring
Name.
newCampaignobject or null
The campaign it creates at publish.
newCampaign.bidStrategystring
Bid strategy.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
newCampaign.budgetstring
In the ad account currency; empty until set (a draft's new campaign starts without a budget unless the workspace's campaign defaults have one).
newCampaign.budgetModestring
campaign (Advantage campaign budget) or ad_set.One of campaign, ad_set
newCampaign.budgetPeriodstring
Period.One of daily, lifetime
newCampaign.budgetSharingboolean
Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.namestring
Name.
newCampaign.objectivestring
Meta objective.One of OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION
newCampaign.specialAdCategoriesarray of strings
Special ad categories.
newCampaign.spendCapstring
Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
platformstring
The ad platform it belongs to (meta, or a platform from GET /platforms); fixed at creation.
platformSettingsobject or null
The platform's own launch settings (GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta.
publishJobIdstring (uuid) or null
The latest publish job.
publishedAtstring (date-time) or null
First published.
scheduleAtstring (date-time) or null
When publishing starts.
settingsobject
The launch's settings its ad sets and ads inherit. Meta: all of them. Another platform: only the content every platform shares (primaryTexts, headlines, descriptions, cta, websiteUrl, utm, adNaming, adSetNaming, delivery); its own settings are platformSettings.
sharedWithGuestsboolean
Shared with the workspace's guests for review.
statusstring
Status.One of draft, publishing, published, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: d33807c9-1c45-4e2a-8a1c-2e3eef207057" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_741877585619437",
    "campaignId": "120227168091908311",
    "expectedVersion": 3,
    "label": "Fall launch",
    "name": "Fall launch",
    "newCampaign": {
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": "150.00",
      "budgetMode": "campaign",
      "budgetPeriod": "daily",
      "budgetSharing": true,
      "name": "Daily budget",
      "objective": "OUTCOME_AWARENESS",
      "specialAdCategories": [
        "FINANCIAL_PRODUCTS_SERVICES"
      ],
      "specialAdCategoryCountry": [],
      "spendCap": "25.00"
    },
    "platform": "adAccountId",
    "platformSettings": {},
    "scheduleAt": "2026-09-30T13:00:00Z",
    "settings": {
      "adNaming": "2026-09-27",
      "adSetNaming": "Brevanne",
      "advantagePlacements": true,
      "audience": "Advantage+ audience",
      "beneficiary": "Brevanne, Inc.",
      "catalogItems": true,
      "clickAttribution": "1 day",
      "conversionEvent": "PURCHASE",
      "creative": {
        "carousel": [
          "text_optimizations"
        ],
        "image": [
          "text_optimizations"
        ],
        "video": [
          "text_optimizations"
        ]
      },
      "cta": "Apply now",
      "customConversion": "1",
      "delivery": "Paused",
      "descriptions": [
        "Two drops every morning for brighter, even skin."
      ],
      "engagedAttribution": "Off",
      "headlines": [
        "Brighter skin in 14 days"
      ],
      "instagram": "Brevanne",
      "multiAdvertiser": true,
      "page": "Brevanne",
      "payer": "Brevanne, Inc.",
      "pixel": "Brevanne",
      "placementCrops": "off",
      "placementPositions": [
        "facebook.feed"
      ],
      "placements": [
        "Facebook"
      ],
      "primaryTexts": [
        "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50."
      ],
      "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd",
      "utm": "https://brevanne.com/products/vitamin-c-serum",
      "viewAttribution": "Off",
      "websiteUrl": "https://brevanne.com/products/vitamin-c-serum"
    },
    "sharedWithGuests": true
  }'
DELETE/launches/{id}

Delete a draft launch

Only drafts that never created anything at a provider.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

Deleted IDs.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 87cd9336-801c-4dba-9b38-a631f5a1f33d"
GET/launches/{id}/ad-sets

List launch ad sets

The launch's ad sets in board order, each with adCount (its ads on the board), without the ads: for listing or picking ad sets without reading the launch document. Archived ad sets are left out.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500, default 200).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page, in board order.
items[].effectiveobject
The launch settings with the overrides on top.
items[].externalKeystring or null
Your own key.
items[].idstring (uuid)Required
ID.
items[].invalidarray of objects
Only in a write's answer: values of the ad set (its own or the launch's it inherits) kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
items[].invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
items[].invalid[].messagestringRequired
Problem.
items[].launchIdstring (uuid)
Launch.
items[].namestring
Name.
items[].overridesobject
Only the launch settings this ad set changes.
items[].platformSettingsobject
A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's ({} for Meta).
items[].positioninteger
Order.
items[].targetingobject
The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
items[].versioninteger
Increments on every change; send as expectedVersion.
items[].adCountintegerRequired
Ads in it on the board.
nextAfterstring or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/ad-sets" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/launches/{id}/ad-sets

Create an ad set

A new ad set starts from the workspace's ad set defaults for the launch's platform (GET /defaults/{platform}), with templateId (a template of that platform) applied on top; what you send wins: settings, targeting and overrides on Meta, platformSettings on a platform with its own launch settings. When none of them names locations, a Meta ad set starts in its ad account's country (adAccounts[].country on GET /integrations/meta), or in none when Meta reports no country.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

beforeIdstring (uuid)
Place before.
endstring
Delivery end, like start; "" runs without an end date.
externalKeystring
Your key.
namestring
Name.
overridesobject
Launch settings this ad set changes; null follows the launch again. Prefer settings.
overrides.advantagePlacementsboolean or null
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
overrides.audiencestring or null
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
overrides.beneficiarystring or null
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
overrides.clickAttributionstring or null
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
overrides.conversionEventstring or null
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
overrides.customConversionstring or null
One of the ad account's custom conversions to optimize for instead of a standard event: its numeric Meta ID (search_platform_targeting, platform meta, facet customConversions), with conversionEvent set to its event type. "" for none.
overrides.deliverystring or null
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
overrides.engagedAttributionstring or null
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
overrides.payerstring or null
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
overrides.pixelstring or null
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
overrides.placementPositionsarray of strings or null
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
overrides.placementsarray of strings or null
Manual placements: the platforms to show on (with advantagePlacements false).
overrides.viewAttributionstring or null
View-through attribution window: "Off" or "1 day".One of Off, 1 day
platformSettingsobject
A launch on a platform with its own settings: the ad set fields of GET /platforms/{platform}/spec this ad set changes from the launch's; null on a key follows the launch again.
settingsobject
Ad set settings, flat; keys left out stay as they are. Launch settings named here (pixel, conversionEvent, audience, attribution, placements, delivery, beneficiary, payer) become this ad set's own values where they differ from the launch's ad set defaults.
settings.advantagePlacementsboolean
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
settings.audiencestring
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
settings.beneficiarystring
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
settings.bidAmountstring
The cost per result goal (bid strategy COST_CAP) or bid cap (LOWEST_COST_WITH_BID_CAP), as a decimal string in the ad account's currency ("30" is 30.00). The bid strategy is the campaign's.
settings.budgetstring
Ad set budget as a decimal string in the ad account's currency ("50", "49.99"), when the campaign uses ad set budgets (budgetMode ad_set).
settings.budgetPeriodstring
daily: spend about this much per day. lifetime: spend it over the ad set's whole schedule (needs an end).One of daily, lifetime
settings.clickAttributionstring
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
settings.conversionEventstring
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
settings.countriesarray of strings
Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
settings.currencystring
ISO 4217 currency of budget and bidAmount: required with them, and must be the ad account's (a launch's ad account currency is in get_launch). Amounts in another currency are refused, never converted.
settings.customAudienceIdsstring
Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
settings.deliverystring
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
settings.devicesarray of strings
Devices: mobile, desktop or both (at least one).
settings.engagedAttributionstring
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
settings.excludedAudienceIdsstring
Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
settings.excludedCountriesarray of strings
Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
settings.excludedPlacesarray of objects
Places to leave out, like places (not in housing, employment or financial ads). A place can't be both included and excluded. [] clears.
settings.excludedPlaces[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
settings.excludedPlaces[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
settings.excludedPlaces[].keystring
The location search's key (not for pins).
settings.excludedPlaces[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
settings.excludedPlaces[].latitudenumber
A pin's latitude.
settings.excludedPlaces[].longitudenumber
A pin's longitude.
settings.excludedPlaces[].namestring
How it reads, as the search named it; a pin's label.
settings.excludedPlaces[].radiusnumber
Distance around a city or pin, in unit.
settings.excludedPlaces[].regionstring
The region or state a city or postal code is in.
settings.excludedPlaces[].unitstring
The radius's unit.One of kilometer, mile
settings.genderstring
Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of All, Women, Men
settings.interestIdsstring
Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
settings.localeIdsstring
Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
settings.maxAgeinteger
Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
settings.minAgeinteger
Minimum age, 13 to 65. With Advantage+ audience Meta takes 18 to 25 as a hard minimum; under 18 needs Original audience with age and location only.
settings.optimizationstring
Performance goal (Meta's optimization goal). inherit uses the objective's default (Sales: OFFSITE_CONVERSIONS). Offered per campaign objective: Awareness: REACH (Maximize reach of ads), IMPRESSIONS (Maximize number of impressions), AD_RECALL_LIFT (Maximize ad recall lift), THRUPLAY (Maximize ThruPlay views); Traffic: LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Engagement: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Leads: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); App promotion: APP_INSTALLS (Maximize number of app installs), OFFSITE_CONVERSIONS (Maximize number of app events), VALUE (Maximize value of conversions); Sales: OFFSITE_CONVERSIONS (Maximize number of conversions), VALUE (Maximize value of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach). A goal the launch's new campaign doesn't offer is refused.One of inherit, REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY, LANDING_PAGE_VIEWS, LINK_CLICKS, OFFSITE_CONVERSIONS, APP_INSTALLS, VALUE
settings.payerstring
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
settings.pixelstring
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
settings.placementPositionsarray of strings
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
settings.placementsarray of strings
Manual placements: the platforms to show on (with advantagePlacements false).
settings.placesarray of objects
Regions, cities, postal codes, markets (DMAs) and pins to reach beyond whole countries. Take each from search_platform_targeting (platform meta, facet locations) as it answers; a pin is {kind: pin, name, address} (Meta places the street address; the publish checklist says when it can't) or {kind: pin, name, latitude, longitude}, with a radius and unit. A city may have a radius of 17 to 80 km or 10 to 50 mi (whole numbers); a pin needs one of 1 to 80 km or 0.63 to 50 mi. A place inside one of countries overlaps it: use one or the other. Housing, employment and financial ads take no postal codes and need radii of at least 25 km (15 mi), 15 km in Europe. [] clears.
settings.places[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
settings.places[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
settings.places[].keystring
The location search's key (not for pins).
settings.places[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
settings.places[].latitudenumber
A pin's latitude.
settings.places[].longitudenumber
A pin's longitude.
settings.places[].namestring
How it reads, as the search named it; a pin's label.
settings.places[].radiusnumber
Distance around a city or pin, in unit.
settings.places[].regionstring
The region or state a city or postal code is in.
settings.places[].unitstring
The radius's unit.One of kilometer, mile
settings.roasGoalstring
Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
settings.viewAttributionstring
View-through attribution window: "Off" or "1 day".One of Off, 1 day
startstring
Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.
targetingobject
The ad set's stored targeting, merged key by key (null removes a key). Prefer settings, which takes the same values flat.
targeting.bidAmountstring
The cost per result goal (bid strategy COST_CAP) or bid cap (LOWEST_COST_WITH_BID_CAP), as a decimal string in the ad account's currency ("30" is 30.00). The bid strategy is the campaign's.
targeting.budgetstring
Ad set budget as a decimal string in the ad account's currency ("50", "49.99"), when the campaign uses ad set budgets (budgetMode ad_set).
targeting.budgetPeriodstring
daily: spend about this much per day. lifetime: spend it over the ad set's whole schedule (needs an end).One of daily, lifetime
targeting.countriesarray of strings
Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
targeting.excludedCountriesarray of strings
Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
targeting.excludedPlacesarray of objects
Places to leave out, like places (not in housing, employment or financial ads). A place can't be both included and excluded. [] clears.
targeting.excludedPlaces[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
targeting.excludedPlaces[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
targeting.excludedPlaces[].keystring
The location search's key (not for pins).
targeting.excludedPlaces[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
targeting.excludedPlaces[].latitudenumber
A pin's latitude.
targeting.excludedPlaces[].longitudenumber
A pin's longitude.
targeting.excludedPlaces[].namestring
How it reads, as the search named it; a pin's label.
targeting.excludedPlaces[].radiusnumber
Distance around a city or pin, in unit.
targeting.excludedPlaces[].regionstring
The region or state a city or postal code is in.
targeting.excludedPlaces[].unitstring
The radius's unit.One of kilometer, mile
targeting.genderstring
Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of All, Women, Men
targeting.maxAgeinteger
Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
targeting.metaSettingsobject
Launch settings this ad set changes; null follows the launch again. Prefer settings.
targeting.metaSettings.advantagePlacementsboolean or null
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
targeting.metaSettings.audiencestring or null
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
targeting.metaSettings.beneficiarystring or null
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
targeting.metaSettings.clickAttributionstring or null
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
targeting.metaSettings.conversionEventstring or null
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
targeting.metaSettings.customConversionstring or null
One of the ad account's custom conversions to optimize for instead of a standard event: its numeric Meta ID (search_platform_targeting, platform meta, facet customConversions), with conversionEvent set to its event type. "" for none.
targeting.metaSettings.deliverystring or null
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
targeting.metaSettings.engagedAttributionstring or null
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
targeting.metaSettings.payerstring or null
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
targeting.metaSettings.pixelstring or null
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
targeting.metaSettings.placementPositionsarray of strings or null
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
targeting.metaSettings.placementsarray of strings or null
Manual placements: the platforms to show on (with advantagePlacements false).
targeting.metaSettings.viewAttributionstring or null
View-through attribution window: "Off" or "1 day".One of Off, 1 day
targeting.minAgeinteger
Minimum age, 13 to 65. With Advantage+ audience Meta takes 18 to 25 as a hard minimum; under 18 needs Original audience with age and location only.
targeting.placesarray of objects
Regions, cities, postal codes, markets (DMAs) and pins to reach beyond whole countries. Take each from search_platform_targeting (platform meta, facet locations) as it answers; a pin is {kind: pin, name, address} (Meta places the street address; the publish checklist says when it can't) or {kind: pin, name, latitude, longitude}, with a radius and unit. A city may have a radius of 17 to 80 km or 10 to 50 mi (whole numbers); a pin needs one of 1 to 80 km or 0.63 to 50 mi. A place inside one of countries overlaps it: use one or the other. Housing, employment and financial ads take no postal codes and need radii of at least 25 km (15 mi), 15 km in Europe. [] clears.
targeting.places[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
targeting.places[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
targeting.places[].keystring
The location search's key (not for pins).
targeting.places[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
targeting.places[].latitudenumber
A pin's latitude.
targeting.places[].longitudenumber
A pin's longitude.
targeting.places[].namestring
How it reads, as the search named it; a pin's label.
targeting.places[].radiusnumber
Distance around a city or pin, in unit.
targeting.places[].regionstring
The region or state a city or postal code is in.
targeting.places[].unitstring
The radius's unit.One of kilometer, mile
targeting.roasGoalstring
Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
targeting.setupobject
Setup: performance goal, audiences, devices and delivery times.
targeting.setup.customAudienceIdsstring
Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
targeting.setup.devicesarray of strings
Devices: mobile, desktop or both (at least one).
targeting.setup.endstring
Delivery end, like start; "" runs without an end date. A lifetime budget needs one.
targeting.setup.excludedAudienceIdsstring
Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
targeting.setup.interestIdsstring
Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
targeting.setup.localeIdsstring
Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
targeting.setup.optimizationstring
Performance goal (Meta's optimization goal). inherit uses the objective's default (Sales: OFFSITE_CONVERSIONS). Offered per campaign objective: Awareness: REACH (Maximize reach of ads), IMPRESSIONS (Maximize number of impressions), AD_RECALL_LIFT (Maximize ad recall lift), THRUPLAY (Maximize ThruPlay views); Traffic: LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Engagement: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Leads: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); App promotion: APP_INSTALLS (Maximize number of app installs), OFFSITE_CONVERSIONS (Maximize number of app events), VALUE (Maximize value of conversions); Sales: OFFSITE_CONVERSIONS (Maximize number of conversions), VALUE (Maximize value of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach). A goal the launch's new campaign doesn't offer is refused.One of inherit, REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY, LANDING_PAGE_VIEWS, LINK_CLICKS, OFFSITE_CONVERSIONS, APP_INSTALLS, VALUE
targeting.setup.startstring
Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.
templateIdstring (uuid)
Start from this ad set template.

Response201 Created

effectiveobject
The launch settings with the overrides on top.
externalKeystring or null
Your own key.
idstring (uuid)Required
ID.
invalidarray of objects
Only in a write's answer: values of the ad set (its own or the launch's it inherits) kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
invalid[].messagestringRequired
Problem.
launchIdstring (uuid)
Launch.
namestring
Name.
overridesobject
Only the launch settings this ad set changes.
platformSettingsobject
A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's ({} for Meta).
positioninteger
Order.
targetingobject
The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
versioninteger
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/ad-sets" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 038e1922-5895-48e9-9bdc-a427e62d5069" \
  -H "Content-Type: application/json" \
  -d '{
    "beforeId": "2d6da6a4-f1d1-47c6-a1f6-3a3b32c6e8b7",
    "end": "2026-09-30T13:00:00Z",
    "externalKey": "fall-2026-launch",
    "name": "Fall launch",
    "overrides": {
      "advantagePlacements": true,
      "audience": "Advantage+ audience",
      "beneficiary": "Brevanne, Inc.",
      "clickAttribution": "1 day",
      "conversionEvent": "PURCHASE",
      "customConversion": "1",
      "delivery": "Paused",
      "engagedAttribution": "Off",
      "payer": "Brevanne, Inc.",
      "pixel": "Brevanne",
      "placementPositions": [
        "facebook.feed"
      ],
      "placements": [
        "Facebook"
      ],
      "viewAttribution": "Off"
    },
    "platformSettings": {},
    "settings": {
      "advantagePlacements": true,
      "audience": "Advantage+ audience",
      "beneficiary": "Brevanne, Inc.",
      "bidAmount": "25.00",
      "budget": "150.00",
      "budgetPeriod": "daily",
      "clickAttribution": "1 day",
      "conversionEvent": "PURCHASE",
      "countries": [
        "US"
      ],
      "currency": "USD",
      "customAudienceIds": "6f8ce1a8-2f6e-4fb7-8089-b19d125f4f1c",
      "delivery": "Paused",
      "devices": [
        "mobile"
      ],
      "engagedAttribution": "Off",
      "excludedAudienceIds": "1b9db722-3ca4-47ad-8e86-aff3cc679b41",
      "excludedCountries": [
        "1000"
      ],
      "excludedPlaces": [
        {
          "address": "Brevanne",
          "country": "US",
          "key": "sk_0GzvHt5ThXfLoYyM7sL0d6uIai49UdKu",
          "kind": "region",
          "latitude": 1.5,
          "longitude": 1.5,
          "name": "Vitamin C Serum, UGC 9x16",
          "radius": 1.5,
          "region": "NY",
          "unit": "kilometer"
        }
      ],
      "gender": "All",
      "interestIds": "42440eaf-b8ef-48c7-8f73-6764316617d2",
      "localeIds": "e80fde70-a540-4088-973c-0680d6a414b3",
      "maxAge": 13,
      "minAge": 13,
      "optimization": "inherit",
      "payer": "Brevanne, Inc.",
      "pixel": "Brevanne",
      "placementPositions": [
        "facebook.feed"
      ],
      "placements": [
        "Facebook"
      ],
      "places": [
        {
          "address": "Brevanne",
          "country": "US",
          "key": "sk_0GzvHt5ThXfLoYyM7sL0d6uIai49UdKu",
          "kind": "region",
          "latitude": 1.5,
          "longitude": 1.5,
          "name": "Vitamin C Serum, UGC 9x16",
          "radius": 1.5,
          "region": "NY",
          "unit": "kilometer"
        }
      ],
      "roasGoal": "Brevanne",
      "viewAttribution": "Off"
    },
    "start": "2026-09-01",
    "targeting": {
      "bidAmount": "25.00",
      "budget": "150.00",
      "budgetPeriod": "daily",
      "countries": [
        "US"
      ],
      "excludedCountries": [
        "1000"
      ],
      "excludedPlaces": [
        {
          "address": "Brevanne",
          "country": "US",
          "key": "sk_b3B5Rw4211v7nBkiHfBWeOd17Ntdld7u",
          "kind": "region",
          "latitude": 1.5,
          "longitude": 1.5,
          "name": "Vitamin C Serum, UGC 9x16",
          "radius": 1.5,
          "region": "NY",
          "unit": "kilometer"
        }
      ],
      "gender": "All",
      "maxAge": 13,
      "metaSettings": {
        "advantagePlacements": true,
        "audience": "Advantage+ audience",
        "beneficiary": "Brevanne, Inc.",
        "clickAttribution": "1 day",
        "conversionEvent": "PURCHASE",
        "customConversion": "1",
        "delivery": "Paused",
        "engagedAttribution": "Off",
        "payer": "Brevanne, Inc.",
        "pixel": "Brevanne",
        "placementPositions": [
          "facebook.feed"
        ],
        "placements": [
          "Facebook"
        ],
        "viewAttribution": "Off"
      },
      "minAge": 13,
      "places": [
        {
          "address": "Brevanne",
          "country": "US",
          "key": "sk_b3B5Rw4211v7nBkiHfBWeOd17Ntdld7u",
          "kind": "region",
          "latitude": 1.5,
          "longitude": 1.5,
          "name": "Vitamin C Serum, UGC 9x16",
          "radius": 1.5,
          "region": "NY",
          "unit": "kilometer"
        }
      ],
      "roasGoal": "Brevanne",
      "setup": {
        "customAudienceIds": "6f8ce1a8-2f6e-4fb7-8089-b19d125f4f1c",
        "devices": [
          "mobile"
        ],
        "end": "2026-09-30T13:00:00Z",
        "excludedAudienceIds": "1b9db722-3ca4-47ad-8e86-aff3cc679b41",
        "interestIds": "42440eaf-b8ef-48c7-8f73-6764316617d2",
        "localeIds": "e80fde70-a540-4088-973c-0680d6a414b3",
        "optimization": "inherit",
        "start": "2026-09-01"
      }
    },
    "templateId": "a39ffff6-3eab-4880-baee-3e4e46b858d6"
  }'
POST/launches/{id}/ad-sets/batch

Create ad sets in bulk

Each item carries its own commandId (an idempotency key for that item, interchangeable with the Idempotency-Key of POST /launches/{id}/ad-sets) and gets its own outcome; a bad item never fails the others. 1 to 1000 items.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

itemsarray of objectsRequired
Ad sets.
items[].beforeIdstring (uuid)
Place before.
items[].commandIdstringRequired
This item's command ID.
items[].endstring
Delivery end, like start; "" runs without an end date.
items[].externalKeystring
Your key.
items[].namestring
Name.
items[].overridesobject
Launch settings this ad set changes; null follows the launch again. Prefer settings.
items[].overrides.advantagePlacementsboolean or null
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
items[].overrides.audiencestring or null
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
items[].overrides.beneficiarystring or null
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].overrides.clickAttributionstring or null
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
items[].overrides.conversionEventstring or null
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
items[].overrides.customConversionstring or null
One of the ad account's custom conversions to optimize for instead of a standard event: its numeric Meta ID (search_platform_targeting, platform meta, facet customConversions), with conversionEvent set to its event type. "" for none.
items[].overrides.deliverystring or null
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
items[].overrides.engagedAttributionstring or null
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
items[].overrides.payerstring or null
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].overrides.pixelstring or null
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].overrides.placementPositionsarray of strings or null
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
items[].overrides.placementsarray of strings or null
Manual placements: the platforms to show on (with advantagePlacements false).
items[].overrides.viewAttributionstring or null
View-through attribution window: "Off" or "1 day".One of Off, 1 day
items[].settingsobject
Ad set settings, flat; keys left out stay as they are. Launch settings named here (pixel, conversionEvent, audience, attribution, placements, delivery, beneficiary, payer) become this ad set's own values where they differ from the launch's ad set defaults.
items[].settings.advantagePlacementsboolean
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
items[].settings.audiencestring
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
items[].settings.beneficiarystring
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].settings.bidAmountstring
The cost per result goal (bid strategy COST_CAP) or bid cap (LOWEST_COST_WITH_BID_CAP), as a decimal string in the ad account's currency ("30" is 30.00). The bid strategy is the campaign's.
items[].settings.budgetstring
Ad set budget as a decimal string in the ad account's currency ("50", "49.99"), when the campaign uses ad set budgets (budgetMode ad_set).
items[].settings.budgetPeriodstring
daily: spend about this much per day. lifetime: spend it over the ad set's whole schedule (needs an end).One of daily, lifetime
items[].settings.clickAttributionstring
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
items[].settings.conversionEventstring
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
items[].settings.countriesarray of strings
Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
items[].settings.currencystring
ISO 4217 currency of budget and bidAmount: required with them, and must be the ad account's (a launch's ad account currency is in get_launch). Amounts in another currency are refused, never converted.
items[].settings.customAudienceIdsstring
Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
items[].settings.deliverystring
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
items[].settings.devicesarray of strings
Devices: mobile, desktop or both (at least one).
items[].settings.engagedAttributionstring
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
items[].settings.excludedAudienceIdsstring
Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
items[].settings.excludedCountriesarray of strings
Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
items[].settings.excludedPlacesarray of objects
Places to leave out, like places (not in housing, employment or financial ads). A place can't be both included and excluded. [] clears.
items[].settings.excludedPlaces[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
items[].settings.excludedPlaces[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
items[].settings.excludedPlaces[].keystring
The location search's key (not for pins).
items[].settings.excludedPlaces[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
items[].settings.excludedPlaces[].latitudenumber
A pin's latitude.
items[].settings.excludedPlaces[].longitudenumber
A pin's longitude.
items[].settings.excludedPlaces[].namestring
How it reads, as the search named it; a pin's label.
items[].settings.excludedPlaces[].radiusnumber
Distance around a city or pin, in unit.
items[].settings.excludedPlaces[].regionstring
The region or state a city or postal code is in.
items[].settings.excludedPlaces[].unitstring
The radius's unit.One of kilometer, mile
items[].settings.genderstring
Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of All, Women, Men
items[].settings.interestIdsstring
Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
items[].settings.localeIdsstring
Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
items[].settings.maxAgeinteger
Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
items[].settings.minAgeinteger
Minimum age, 13 to 65. With Advantage+ audience Meta takes 18 to 25 as a hard minimum; under 18 needs Original audience with age and location only.
items[].settings.optimizationstring
Performance goal (Meta's optimization goal). inherit uses the objective's default (Sales: OFFSITE_CONVERSIONS). Offered per campaign objective: Awareness: REACH (Maximize reach of ads), IMPRESSIONS (Maximize number of impressions), AD_RECALL_LIFT (Maximize ad recall lift), THRUPLAY (Maximize ThruPlay views); Traffic: LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Engagement: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Leads: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); App promotion: APP_INSTALLS (Maximize number of app installs), OFFSITE_CONVERSIONS (Maximize number of app events), VALUE (Maximize value of conversions); Sales: OFFSITE_CONVERSIONS (Maximize number of conversions), VALUE (Maximize value of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach). A goal the launch's new campaign doesn't offer is refused.One of inherit, REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY, LANDING_PAGE_VIEWS, LINK_CLICKS, OFFSITE_CONVERSIONS, APP_INSTALLS, VALUE
items[].settings.payerstring
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].settings.pixelstring
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].settings.placementPositionsarray of strings
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
items[].settings.placementsarray of strings
Manual placements: the platforms to show on (with advantagePlacements false).
items[].settings.placesarray of objects
Regions, cities, postal codes, markets (DMAs) and pins to reach beyond whole countries. Take each from search_platform_targeting (platform meta, facet locations) as it answers; a pin is {kind: pin, name, address} (Meta places the street address; the publish checklist says when it can't) or {kind: pin, name, latitude, longitude}, with a radius and unit. A city may have a radius of 17 to 80 km or 10 to 50 mi (whole numbers); a pin needs one of 1 to 80 km or 0.63 to 50 mi. A place inside one of countries overlaps it: use one or the other. Housing, employment and financial ads take no postal codes and need radii of at least 25 km (15 mi), 15 km in Europe. [] clears.
items[].settings.places[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
items[].settings.places[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
items[].settings.places[].keystring
The location search's key (not for pins).
items[].settings.places[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
items[].settings.places[].latitudenumber
A pin's latitude.
items[].settings.places[].longitudenumber
A pin's longitude.
items[].settings.places[].namestring
How it reads, as the search named it; a pin's label.
items[].settings.places[].radiusnumber
Distance around a city or pin, in unit.
items[].settings.places[].regionstring
The region or state a city or postal code is in.
items[].settings.places[].unitstring
The radius's unit.One of kilometer, mile
items[].settings.roasGoalstring
Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
items[].settings.viewAttributionstring
View-through attribution window: "Off" or "1 day".One of Off, 1 day
items[].startstring
Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.
items[].targetingobject
The ad set's stored targeting, merged key by key (null removes a key). Prefer settings, which takes the same values flat.
items[].targeting.bidAmountstring
The cost per result goal (bid strategy COST_CAP) or bid cap (LOWEST_COST_WITH_BID_CAP), as a decimal string in the ad account's currency ("30" is 30.00). The bid strategy is the campaign's.
items[].targeting.budgetstring
Ad set budget as a decimal string in the ad account's currency ("50", "49.99"), when the campaign uses ad set budgets (budgetMode ad_set).
items[].targeting.budgetPeriodstring
daily: spend about this much per day. lifetime: spend it over the ad set's whole schedule (needs an end).One of daily, lifetime
items[].targeting.countriesarray of strings
Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
items[].targeting.excludedCountriesarray of strings
Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
items[].targeting.excludedPlacesarray of objects
Places to leave out, like places (not in housing, employment or financial ads). A place can't be both included and excluded. [] clears.
items[].targeting.excludedPlaces[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
items[].targeting.excludedPlaces[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
items[].targeting.excludedPlaces[].keystring
The location search's key (not for pins).
items[].targeting.excludedPlaces[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
items[].targeting.excludedPlaces[].latitudenumber
A pin's latitude.
items[].targeting.excludedPlaces[].longitudenumber
A pin's longitude.
items[].targeting.excludedPlaces[].namestring
How it reads, as the search named it; a pin's label.
items[].targeting.excludedPlaces[].radiusnumber
Distance around a city or pin, in unit.
items[].targeting.excludedPlaces[].regionstring
The region or state a city or postal code is in.
items[].targeting.excludedPlaces[].unitstring
The radius's unit.One of kilometer, mile
items[].targeting.genderstring
Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of All, Women, Men
items[].targeting.maxAgeinteger
Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
items[].targeting.metaSettingsobject
Launch settings this ad set changes; null follows the launch again. Prefer settings.
items[].targeting.metaSettings.advantagePlacementsboolean or null
true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only placements and placementPositions.
items[].targeting.metaSettings.audiencestring or null
Audience approach. Advantage+ audience: Meta finds people, treating ages above the minimum, gender and audiences as suggestions. Original audience: the targeting is a hard limit.One of Advantage+ audience, Original audience
items[].targeting.metaSettings.beneficiarystring or null
EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].targeting.metaSettings.clickAttributionstring or null
Click-through attribution window: "1 day" or "7 days".One of 1 day, 7 days
items[].targeting.metaSettings.conversionEventstring or null
The website event to optimize for (promoted object): PURCHASE (Purchase), ADD_TO_CART (Add to cart), INITIATED_CHECKOUT (Initiate checkout), ADD_PAYMENT_INFO (Add payment info), CONTENT_VIEW (View content), SEARCH (Search), LEAD (Lead), COMPLETE_REGISTRATION (Complete registration), CONTACT (Contact), SUBSCRIBE (Subscribe), START_TRIAL (Start trial), SCHEDULE (Schedule), SUBMIT_APPLICATION (Submit application), ADD_TO_WISHLIST (Add to wishlist), CUSTOMIZE_PRODUCT (Customize product), DONATE (Donate), FIND_LOCATION (Find location). With a customConversion, that custom conversion's own event type (OTHER too).One of PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, CONTENT_VIEW, SEARCH, LEAD, COMPLETE_REGISTRATION, CONTACT, SUBSCRIBE, START_TRIAL, SCHEDULE, SUBMIT_APPLICATION, ADD_TO_WISHLIST, CUSTOMIZE_PRODUCT, DONATE, FIND_LOCATION, OTHER
items[].targeting.metaSettings.customConversionstring or null
One of the ad account's custom conversions to optimize for instead of a standard event: its numeric Meta ID (search_platform_targeting, platform meta, facet customConversions), with conversionEvent set to its event type. "" for none.
items[].targeting.metaSettings.deliverystring or null
Initial delivery of new ads: Paused publishes them to Meta without spending until turned on; Active delivers once Meta approves.One of Paused, Active
items[].targeting.metaSettings.engagedAttributionstring or null
Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of Off, 1 day
items[].targeting.metaSettings.payerstring or null
EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].targeting.metaSettings.pixelstring or null
The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].targeting.metaSettings.placementPositionsarray of strings or null
Manual placements: the positions to show in, as platform.position keys, only within the chosen placements ("Reels and Stories only" is facebook.story, facebook.facebook_reels, instagram.story, instagram.reels with placements Facebook and Instagram). Every key: facebook.feed (Facebook Feed), facebook.profile_feed (Facebook Profile feed), facebook.marketplace (Facebook Marketplace), facebook.story (Facebook Stories), facebook.facebook_reels (Facebook Reels), facebook.facebook_reels_overlay (Facebook Ads on Reels), facebook.search (Facebook Search results), facebook.instream_video (Facebook In-stream videos), facebook.right_hand_column (Facebook Right column), facebook.notification (Facebook Notifications), instagram.stream (Instagram Feed), instagram.profile_feed (Instagram Profile feed), instagram.story (Instagram Stories), instagram.reels (Instagram Reels), instagram.profile_reels (Instagram Profile reels), instagram.ig_search (Instagram Search results), instagram.explore_home (Instagram Explore home), audience_network.classic (Audience Network Native, banner and interstitial), audience_network.rewarded_video (Audience Network Rewarded videos), messenger.sponsored_messages (Messenger Sponsored messages), threads.threads_stream (Threads Feed).
items[].targeting.metaSettings.placementsarray of strings or null
Manual placements: the platforms to show on (with advantagePlacements false).
items[].targeting.metaSettings.viewAttributionstring or null
View-through attribution window: "Off" or "1 day".One of Off, 1 day
items[].targeting.minAgeinteger
Minimum age, 13 to 65. With Advantage+ audience Meta takes 18 to 25 as a hard minimum; under 18 needs Original audience with age and location only.
items[].targeting.placesarray of objects
Regions, cities, postal codes, markets (DMAs) and pins to reach beyond whole countries. Take each from search_platform_targeting (platform meta, facet locations) as it answers; a pin is {kind: pin, name, address} (Meta places the street address; the publish checklist says when it can't) or {kind: pin, name, latitude, longitude}, with a radius and unit. A city may have a radius of 17 to 80 km or 10 to 50 mi (whole numbers); a pin needs one of 1 to 80 km or 0.63 to 50 mi. A place inside one of countries overlaps it: use one or the other. Housing, employment and financial ads take no postal codes and need radii of at least 25 km (15 mi), 15 km in Europe. [] clears.
items[].targeting.places[].addressstring
A pin's street address as written ("Sommerfugleengen 66, 8600 Silkeborg"): Meta places it, so it needs no latitude or longitude. A pin has an address or a latitude and longitude.
items[].targeting.places[].countrystring
Its ISO 3166-1 alpha-2 country, as the search answered.
items[].targeting.places[].keystring
The location search's key (not for pins).
items[].targeting.places[].kindstringRequired
region, city, postalCode, market (a DMA) or pin.One of region, city, postalCode, market, pin
items[].targeting.places[].latitudenumber
A pin's latitude.
items[].targeting.places[].longitudenumber
A pin's longitude.
items[].targeting.places[].namestring
How it reads, as the search named it; a pin's label.
items[].targeting.places[].radiusnumber
Distance around a city or pin, in unit.
items[].targeting.places[].regionstring
The region or state a city or postal code is in.
items[].targeting.places[].unitstring
The radius's unit.One of kilometer, mile
items[].targeting.roasGoalstring
Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
items[].targeting.setupobject
Setup: performance goal, audiences, devices and delivery times.
items[].targeting.setup.customAudienceIdsstring
Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
items[].targeting.setup.devicesarray of strings
Devices: mobile, desktop or both (at least one).
items[].targeting.setup.endstring
Delivery end, like start; "" runs without an end date. A lifetime budget needs one.
items[].targeting.setup.excludedAudienceIdsstring
Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
items[].targeting.setup.interestIdsstring
Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
items[].targeting.setup.localeIdsstring
Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
items[].targeting.setup.optimizationstring
Performance goal (Meta's optimization goal). inherit uses the objective's default (Sales: OFFSITE_CONVERSIONS). Offered per campaign objective: Awareness: REACH (Maximize reach of ads), IMPRESSIONS (Maximize number of impressions), AD_RECALL_LIFT (Maximize ad recall lift), THRUPLAY (Maximize ThruPlay views); Traffic: LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Engagement: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); Leads: OFFSITE_CONVERSIONS (Maximize number of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach); App promotion: APP_INSTALLS (Maximize number of app installs), OFFSITE_CONVERSIONS (Maximize number of app events), VALUE (Maximize value of conversions); Sales: OFFSITE_CONVERSIONS (Maximize number of conversions), VALUE (Maximize value of conversions), LANDING_PAGE_VIEWS (Maximize number of landing page views), LINK_CLICKS (Maximize number of link clicks), IMPRESSIONS (Maximize number of impressions), REACH (Maximize daily unique reach). A goal the launch's new campaign doesn't offer is refused.One of inherit, REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY, LANDING_PAGE_VIEWS, LINK_CLICKS, OFFSITE_CONVERSIONS, APP_INSTALLS, VALUE
items[].targeting.setup.startstring
Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.

Response200 OK

itemsarray of objectsRequired
One outcome per item, in order: adSet when accepted; errors when rejected (a commandId reused for other input is rejected on commandId); message on a conflict.
items[].adSetobject
An ad set. Stores explicit overrides only; empty means inherit from the launch.
items[].adSet.effectiveobject
The launch settings with the overrides on top.
items[].adSet.externalKeystring or null
Your own key.
items[].adSet.idstring (uuid)Required
ID.
items[].adSet.invalidarray of objects
Only in a write's answer: values of the ad set (its own or the launch's it inherits) kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
items[].adSet.invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
items[].adSet.invalid[].messagestringRequired
Problem.
items[].adSet.launchIdstring (uuid)
Launch.
items[].adSet.namestring
Name.
items[].adSet.overridesobject
Only the launch settings this ad set changes.
items[].adSet.platformSettingsobject
A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's ({} for Meta).
items[].adSet.positioninteger
Order.
items[].adSet.targetingobject
The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
items[].adSet.versioninteger
Increments on every change; send as expectedVersion.
items[].commandIdstringRequired
The item's command ID.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].messagestring
Why it conflicts.
items[].messageCodestring
A registered message's stable code (such as ad_exists_in_launch), for an app to say it in its language.
items[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].statusstringRequired
Outcome of this item.One of accepted, rejected, conflict

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/ad-sets/batch" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 9a2608a8-b899-43ed-9672-b249b6ac68aa" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "beforeId": "2d6da6a4-f1d1-47c6-a1f6-3a3b32c6e8b7",
        "commandId": "ca4b1318-93a6-403c-9e0c-0e2ff51907bd",
        "end": "2026-09-30T13:00:00Z",
        "externalKey": "fall-2026-launch",
        "name": "Vitamin C Serum",
        "overrides": {
          "advantagePlacements": true,
          "audience": "Advantage+ audience",
          "beneficiary": "Brevanne, Inc.",
          "clickAttribution": "1 day",
          "conversionEvent": "PURCHASE",
          "customConversion": "1",
          "delivery": "Paused",
          "engagedAttribution": "Off",
          "payer": "Brevanne, Inc.",
          "pixel": "Brevanne",
          "placementPositions": [
            "facebook.feed"
          ],
          "placements": [
            "Facebook"
          ],
          "viewAttribution": "Off"
        },
        "settings": {
          "advantagePlacements": true,
          "audience": "Advantage+ audience",
          "beneficiary": "Brevanne, Inc.",
          "bidAmount": "25.00",
          "budget": "150.00",
          "budgetPeriod": "daily",
          "clickAttribution": "1 day",
          "conversionEvent": "PURCHASE",
          "countries": [
            "US"
          ],
          "currency": "USD",
          "customAudienceIds": "6f8ce1a8-2f6e-4fb7-8089-b19d125f4f1c",
          "delivery": "Paused",
          "devices": [
            "mobile"
          ],
          "engagedAttribution": "Off",
          "excludedAudienceIds": "1b9db722-3ca4-47ad-8e86-aff3cc679b41",
          "excludedCountries": [
            "1000"
          ],
          "excludedPlaces": [
            {
              "address": "Brevanne",
              "country": "US",
              "key": "sk_0GzvHt5ThXfLoYyM7sL0d6uIai49UdKu",
              "kind": "region",
              "latitude": 1.5,
              "longitude": 1.5,
              "name": "Vitamin C Serum, UGC 9x16",
              "radius": 1.5,
              "region": "NY",
              "unit": "kilometer"
            }
          ],
          "gender": "All",
          "interestIds": "42440eaf-b8ef-48c7-8f73-6764316617d2",
          "localeIds": "e80fde70-a540-4088-973c-0680d6a414b3",
          "maxAge": 13,
          "minAge": 13,
          "optimization": "inherit",
          "payer": "Brevanne, Inc.",
          "pixel": "Brevanne",
          "placementPositions": [
            "facebook.feed"
          ],
          "placements": [
            "Facebook"
          ],
          "places": [
            {
              "address": "Brevanne",
              "country": "US",
              "key": "sk_0GzvHt5ThXfLoYyM7sL0d6uIai49UdKu",
              "kind": "region",
              "latitude": 1.5,
              "longitude": 1.5,
              "name": "Vitamin C Serum, UGC 9x16",
              "radius": 1.5,
              "region": "NY",
              "unit": "kilometer"
            }
          ],
          "roasGoal": "Brevanne",
          "viewAttribution": "Off"
        },
        "start": "2026-09-01",
        "targeting": {
          "bidAmount": "25.00",
          "budget": "150.00",
          "budgetPeriod": "daily",
          "countries": [
            "US"
          ],
          "excludedCountries": [
            "1000"
          ],
          "excludedPlaces": [
            {
              "address": "Brevanne",
              "country": "US",
              "key": "sk_b3B5Rw4211v7nBkiHfBWeOd17Ntdld7u",
              "kind": "region",
              "latitude": 1.5,
              "longitude": 1.5,
              "name": "Vitamin C Serum, UGC 9x16",
              "radius": 1.5,
              "region": "NY",
              "unit": "kilometer"
            }
          ],
          "gender": "All",
          "maxAge": 13,
          "metaSettings": {
            "advantagePlacements": true,
            "audience": "Advantage+ audience",
            "beneficiary": "Brevanne, Inc.",
            "clickAttribution": "1 day",
            "conversionEvent": "PURCHASE",
            "customConversion": "1",
            "delivery": "Paused",
            "engagedAttribution": "Off",
            "payer": "Brevanne, Inc.",
            "pixel": "Brevanne",
            "placementPositions": [
              "facebook.feed"
            ],
            "placements": [
              "Facebook"
            ],
            "viewAttribution": "Off"
          },
          "minAge": 13,
          "places": [
            {
              "address": "Brevanne",
              "country": "US",
              "key": "sk_b3B5Rw4211v7nBkiHfBWeOd17Ntdld7u",
              "kind": "region",
              "latitude": 1.5,
              "longitude": 1.5,
              "name": "Vitamin C Serum, UGC 9x16",
              "radius": 1.5,
              "region": "NY",
              "unit": "kilometer"
            }
          ],
          "roasGoal": "Brevanne",
          "setup": {
            "customAudienceIds": "6f8ce1a8-2f6e-4fb7-8089-b19d125f4f1c",
            "devices": [
              "mobile"
            ],
            "end": "2026-09-30T13:00:00Z",
            "excludedAudienceIds": "1b9db722-3ca4-47ad-8e86-aff3cc679b41",
            "interestIds": "42440eaf-b8ef-48c7-8f73-6764316617d2",
            "localeIds": "e80fde70-a540-4088-973c-0680d6a414b3",
            "optimization": "inherit",
            "start": "2026-09-01"
          }
        }
      }
    ]
  }'
POST/launches/{id}/ads/batch

Create ads in bulk

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

itemsarray of objectsRequired
Ads.
items[].adSetIdstring (uuid)
Ad set.
items[].commandIdstringRequired
This item's command ID.
items[].editobject
An edit in effective values. Values equal to the launch's follow the launch. URL parameters are the launch's utm setting unless a Meta ad sets its own.
items[].edit.bestCardsFirstboolean
A carousel shows its best-performing cards first (default true). Meta only.
items[].edit.cardsarray of objects
A carousel ad's cards, all of them in order (2 to 10); replaces the ad's cards. On Meta an ad with cards is a carousel (each card an image or video; the ad's call to action goes on every card, its URL is the "See more" link and the link of a card without its own). On platforms that set the format per ad set, only an ad set whose format is a carousel takes them.
items[].edit.cards[].descriptionstring
The card's description, where the platform shows one.
items[].edit.cards[].headlinestring
The card's headline.
items[].edit.cards[].mediaIdstring (uuid)Required
The card's image or video: a media library ID. The first card's is the ad's media.
items[].edit.cards[].urlstring
The page the card opens (https://…).
items[].edit.creativeobject
Creative settings.
items[].edit.creative.catalogItemsboolean
Show products from your catalog.
items[].edit.creative.featuresobject
Advantage+ creative enhancements per format (each is opt-in).
items[].edit.creative.multiAdvertiserboolean
Multi-advertiser ads.
items[].edit.creative.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
items[].edit.creative.productSetIdstring
Catalog product set: its numeric Meta ID.
items[].edit.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
items[].edit.descriptionstring
Description.
items[].edit.displayLinkstring
Meta: the link the ad shows instead of its website's domain (Ads Manager's Display link); "" removes it.
items[].edit.endCardboolean
A carousel ends with a card showing the Page (default true). Meta only.
items[].edit.headlinestring
Headline.
items[].edit.identityobject
The Page and Instagram account the ad publishes as.
items[].edit.identity.instagramstring
Instagram account: its Meta ID; usually the one linked to the Page.
items[].edit.identity.pagestring
Facebook Page: its numeric Meta ID (get_meta_integration).
items[].edit.imageCropsobject
An image ad's own crop per shape, in the image's pixels (get_media gives its width and height): 1:1 for every placement outside the groups, 4:5 for Feeds, 9:16 for Stories and Reels, 1.91:1 for right column and search. Each box stays inside the image with its shape's proportions, to the pixel. Shapes left out keep theirs; null puts one back in the middle. A box makes the ad crop (creative.placementCrops center). A new image drops the ad's crops.
items[].edit.imageCrops.1.91:1object or null
items[].edit.imageCrops.1:1object or null
items[].edit.imageCrops.4:5object or null
items[].edit.imageCrops.9:16object or null
items[].edit.placementMediaobject
Another image or video (a media library ID) for a group of placements, Meta only: feeds (Facebook and Instagram feeds, profile feeds, Explore home, Threads; 4:5), stories (Stories and Reels; 9:16), rightColumn (right column and search results; 1.91:1). The ad's own file shows everywhere else. An image ad takes images and a video ad videos (Meta takes one kind per ad); never a carousel. Groups left out keep theirs; null removes one.
items[].edit.placementMedia.feedsstring (uuid) or null
items[].edit.placementMedia.rightColumnstring (uuid) or null
items[].edit.placementMedia.storiesstring (uuid) or null
items[].edit.textstring
Primary text.
items[].edit.urlstring
Website URL the ad links to (https://…).
items[].edit.useLauncharray of strings
Follow the launch again for these groups, before the rest of the edit: copy (text, headline, description), destination (CTA, URL, the ad's own URL parameters and display link), identity (Page and Instagram), creativeSettings (enhancements, multi-advertiser, catalog, placementCrops).
items[].edit.utmstring
Meta: the ad's own URL parameters (Ads Manager's per-ad URL parameters, like utm_content={{ad.name}}); the launch's utm value follows the launch again, "" sends none.
items[].externalKeystring
Your key.
items[].mediaIdstring (uuid)Required
The creative: an image or a video from the library. Media still processing is fine; publishing waits for it.
items[].namestring
Name.
items[].overridesobject
Stored overrides; values equal to the launch's collapse to inherit. Prefer edit.
items[].overrides.bestCardsFirstboolean
false when a carousel keeps its card order (default true). Meta only.
items[].overrides.cardsarray of objects
A carousel ad's cards, in order.
items[].overrides.cards[].descriptionstring
The card's description, where the platform shows one.
items[].overrides.cards[].headlinestring
The card's headline.
items[].overrides.cards[].mediaIdstring (uuid)Required
The card's image or video: a media library ID. The first card's is the ad's media.
items[].overrides.cards[].urlstring
The page the card opens (https://…).
items[].overrides.copyVariationsobject
Copy lists this ad changes; a list left out follows the launch.
items[].overrides.copyVariations.descriptionsarray of strings
Description; publishing sends one.
items[].overrides.copyVariations.headlinesarray of strings
Headline; publishing sends one.
items[].overrides.copyVariations.primaryTextsarray of strings
Primary text; publishing sends one.
items[].overrides.creativeSettingsobject
Creative settings this ad changes.
items[].overrides.creativeSettings.catalogItemsboolean
Catalog items.
items[].overrides.creativeSettings.creativeobject
Advantage+ creative enhancements per format (each is opt-in).
items[].overrides.creativeSettings.multiAdvertiserboolean
Multi-advertiser ads.
items[].overrides.creativeSettings.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
items[].overrides.creativeSettings.productSetIdstring
Product set ID.
items[].overrides.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
items[].overrides.endCardboolean
false when a carousel has no end card (default true). Meta only.
items[].overrides.identityobject or null
Page and Instagram account IDs; null follows the launch.
items[].overrides.identity.instagramstring
items[].overrides.identity.pagestring
items[].overrides.imageCropsobject
The ad's own crop per shape, in its image's pixels; shapes left out are cropped in the middle while the ad crops.
items[].overrides.imageCrops.1.91:1object
items[].overrides.imageCrops.1:1object
items[].overrides.imageCrops.4:5object
items[].overrides.imageCrops.9:16object
items[].overrides.placementMediaobject
Another image or video per group of placements (feeds, stories, rightColumn), by media library ID; the ad's own file shows everywhere else.
items[].overrides.placementMedia.feedsstring (uuid)
items[].overrides.placementMedia.rightColumnstring (uuid)
items[].overrides.placementMedia.storiesstring (uuid)
items[].overrides.urlstring
Website URL.
items[].statusIdstring (uuid)
Review status.

Response200 OK

itemsarray of objectsRequired
One outcome per item, in order: ad when accepted; errors when rejected (a commandId reused for other input is rejected on commandId); message on a conflict.
items[].adobject
An ad. Stores explicit overrides only; effective values resolve at read time.
items[].ad.adSetIdstring (uuid) or null
Ad set; null is ungrouped.
items[].ad.assigneeIdstring (uuid) or null
Assignee.
items[].ad.createdAtstring (date-time)
Created.
items[].ad.creativeLinkIdstring (uuid) or null
Shared with the ads copied from or to it in its launch group's other campaigns (GET /ads/{id}/linked).
items[].ad.cropsobject
Meta: an image ad that crops for each placement, the box of each shape it publishes with (1:1, 4:5, 9:16, 1.91:1), in its image's pixels: its own, else the middle. Absent when it doesn't crop or its image isn't measured yet.
items[].ad.effectiveobject
The content the ad publishes: overrides, otherwise the launch's values.
items[].ad.externalKeystring or null
Your own key.
items[].ad.formatstring
Creative format: audio is an audio ad, where the platform has them; text is an ad with no file, no cards and no existing post (an X text Post, a Google or Microsoft search ad, a Reddit free-form ad; where the platform's ads need a file, it is still to come).One of image, video, carousel, audio, text
items[].ad.idstring (uuid)Required
ID.
items[].ad.issuesarray of strings
Problems with the effective content.
items[].ad.labelIdsarray of strings (uuid)
Labels.
items[].ad.launchIdstring (uuid)
Launch.
items[].ad.mediaIdstring (uuid) or null
Creative.
items[].ad.namestring
Name.
items[].ad.overridesobject
Only what this ad changes.
items[].ad.positioninteger
Order.
items[].ad.statusIdstring (uuid) or null
Review status.
items[].ad.updatedAtstring (date-time)
Last change.
items[].ad.versioninteger
Increments on every change; send as expectedVersion.
items[].commandIdstringRequired
The item's command ID.
items[].errorsarray of objects
Every problem with this item.
items[].errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
items[].errors[].fieldstringRequired
JSON-pointer-like path.
items[].errors[].messagestringRequired
Problem.
items[].errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
items[].messagestring
Why it conflicts.
items[].messageCodestring
A registered message's stable code (such as ad_exists_in_launch), for an app to say it in its language.
items[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
items[].statusstringRequired
Outcome of this item.One of accepted, rejected, conflict

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/ads/batch" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 657c50c9-82d0-4d92-bede-e6a39e0ff9ef" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
        "commandId": "ca4b1318-93a6-403c-9e0c-0e2ff51907bd",
        "edit": {
          "bestCardsFirst": true,
          "cards": [
            {
              "description": "Two drops every morning for brighter, even skin.",
              "headline": "Brighter skin in 14 days",
              "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
              "url": "https://brevanne.com/products/vitamin-c-serum"
            }
          ],
          "creative": {
            "catalogItems": true,
            "features": {
              "carousel": {},
              "image": {},
              "video": {}
            },
            "multiAdvertiser": true,
            "placementCrops": "off",
            "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
          },
          "cta": "Apply now",
          "description": "Two drops every morning for brighter, even skin.",
          "displayLink": "Brevanne",
          "endCard": true,
          "headline": "Brighter skin in 14 days",
          "identity": {
            "instagram": "Brevanne",
            "page": "Brevanne"
          },
          "imageCrops": {
            "1.91:1": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            },
            "1:1": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            },
            "4:5": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            },
            "9:16": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            }
          },
          "placementMedia": {
            "feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
            "rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
            "stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
          },
          "text": "Can we try the 4x5 cut for Instagram feed before we publish?",
          "url": "https://brevanne.com/products/vitamin-c-serum",
          "useLaunch": [
            "copy"
          ],
          "utm": "https://brevanne.com/products/vitamin-c-serum"
        },
        "externalKey": "fall-2026-launch",
        "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
        "name": "Vitamin C Serum",
        "overrides": {
          "bestCardsFirst": true,
          "cards": [
            {
              "description": "Two drops every morning for brighter, even skin.",
              "headline": "Brighter skin in 14 days",
              "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
              "url": "https://brevanne.com/products/vitamin-c-serum"
            }
          ],
          "copyVariations": {
            "descriptions": [
              "Two drops every morning for brighter, even skin."
            ],
            "headlines": [
              "Brighter skin in 14 days"
            ],
            "primaryTexts": [
              "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50."
            ]
          },
          "creativeSettings": {
            "catalogItems": true,
            "creative": {
              "carousel": [],
              "image": [],
              "video": []
            },
            "multiAdvertiser": true,
            "placementCrops": "off",
            "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
          },
          "cta": "Apply now",
          "endCard": true,
          "identity": {
            "instagram": "Brevanne",
            "page": "Brevanne"
          },
          "imageCrops": {
            "1.91:1": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            },
            "1:1": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            },
            "4:5": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            },
            "9:16": {
              "height": 1920,
              "width": 1080,
              "x": 3,
              "y": 3
            }
          },
          "placementMedia": {
            "feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
            "rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
            "stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
          },
          "url": "https://brevanne.com/products/vitamin-c-serum"
        },
        "statusId": "069ff91e-35e1-4603-afc3-792b04f09624"
      }
    ]
  }'
POST/launches/{id}/ads/from-media

Create ads from media

One ad per file of a folder (folderId, in order, optionally one kind) or of mediaIds (in that order), up to 5,000, as a job: stages of 50 ads, every one into adSetId or a new ad set (adSetName, adSetSettings). Nothing is split: a Meta ad set filled past Meta's usual 50 ads is offered a split (splitSuggested), which POST /ad-sets/{id}/split makes if wanted, and Meta decides when the launch publishes. Each ad takes the ad template (overrides, edit, statusId) and the launch's ad naming. Files the launch already uses are left out unless includeUsed; failed and archived files always are. Files still uploading or processing are fine: publishing waits for them. 202 with the job; follow it at GET /jobs/{id}.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adobject
ad.editobject
An edit in effective values. Values equal to the launch's follow the launch. URL parameters are the launch's utm setting unless a Meta ad sets its own.
ad.edit.bestCardsFirstboolean
A carousel shows its best-performing cards first (default true). Meta only.
ad.edit.cardsarray of objects
A carousel ad's cards, all of them in order (2 to 10); replaces the ad's cards. On Meta an ad with cards is a carousel (each card an image or video; the ad's call to action goes on every card, its URL is the "See more" link and the link of a card without its own). On platforms that set the format per ad set, only an ad set whose format is a carousel takes them.
ad.edit.cards[].descriptionstring
The card's description, where the platform shows one.
ad.edit.cards[].headlinestring
The card's headline.
ad.edit.cards[].mediaIdstring (uuid)Required
The card's image or video: a media library ID. The first card's is the ad's media.
ad.edit.cards[].urlstring
The page the card opens (https://…).
ad.edit.creativeobject
Creative settings.
ad.edit.creative.catalogItemsboolean
Show products from your catalog.
ad.edit.creative.featuresobject
Advantage+ creative enhancements per format (each is opt-in).
ad.edit.creative.multiAdvertiserboolean
Multi-advertiser ads.
ad.edit.creative.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
ad.edit.creative.productSetIdstring
Catalog product set: its numeric Meta ID.
ad.edit.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
ad.edit.descriptionstring
Description.
ad.edit.displayLinkstring
Meta: the link the ad shows instead of its website's domain (Ads Manager's Display link); "" removes it.
ad.edit.endCardboolean
A carousel ends with a card showing the Page (default true). Meta only.
ad.edit.headlinestring
Headline.
ad.edit.identityobject
The Page and Instagram account the ad publishes as.
ad.edit.identity.instagramstring
Instagram account: its Meta ID; usually the one linked to the Page.
ad.edit.identity.pagestring
Facebook Page: its numeric Meta ID (get_meta_integration).
ad.edit.imageCropsobject
An image ad's own crop per shape, in the image's pixels (get_media gives its width and height): 1:1 for every placement outside the groups, 4:5 for Feeds, 9:16 for Stories and Reels, 1.91:1 for right column and search. Each box stays inside the image with its shape's proportions, to the pixel. Shapes left out keep theirs; null puts one back in the middle. A box makes the ad crop (creative.placementCrops center). A new image drops the ad's crops.
ad.edit.imageCrops.1.91:1object or null
ad.edit.imageCrops.1:1object or null
ad.edit.imageCrops.4:5object or null
ad.edit.imageCrops.9:16object or null
ad.edit.placementMediaobject
Another image or video (a media library ID) for a group of placements, Meta only: feeds (Facebook and Instagram feeds, profile feeds, Explore home, Threads; 4:5), stories (Stories and Reels; 9:16), rightColumn (right column and search results; 1.91:1). The ad's own file shows everywhere else. An image ad takes images and a video ad videos (Meta takes one kind per ad); never a carousel. Groups left out keep theirs; null removes one.
ad.edit.placementMedia.feedsstring (uuid) or null
ad.edit.placementMedia.rightColumnstring (uuid) or null
ad.edit.placementMedia.storiesstring (uuid) or null
ad.edit.textstring
Primary text.
ad.edit.urlstring
Website URL the ad links to (https://…).
ad.edit.useLauncharray of strings
Follow the launch again for these groups, before the rest of the edit: copy (text, headline, description), destination (CTA, URL, the ad's own URL parameters and display link), identity (Page and Instagram), creativeSettings (enhancements, multi-advertiser, catalog, placementCrops).
ad.edit.utmstring
Meta: the ad's own URL parameters (Ads Manager's per-ad URL parameters, like utm_content={{ad.name}}); the launch's utm value follows the launch again, "" sends none.
ad.overridesobject
Stored overrides; values equal to the launch's collapse to inherit. Prefer edit.
ad.overrides.bestCardsFirstboolean
false when a carousel keeps its card order (default true). Meta only.
ad.overrides.cardsarray of objects
A carousel ad's cards, in order.
ad.overrides.cards[].descriptionstring
The card's description, where the platform shows one.
ad.overrides.cards[].headlinestring
The card's headline.
ad.overrides.cards[].mediaIdstring (uuid)Required
The card's image or video: a media library ID. The first card's is the ad's media.
ad.overrides.cards[].urlstring
The page the card opens (https://…).
ad.overrides.copyVariationsobject
Copy lists this ad changes; a list left out follows the launch.
ad.overrides.copyVariations.descriptionsarray of strings
Description; publishing sends one.
ad.overrides.copyVariations.headlinesarray of strings
Headline; publishing sends one.
ad.overrides.copyVariations.primaryTextsarray of strings
Primary text; publishing sends one.
ad.overrides.creativeSettingsobject
Creative settings this ad changes.
ad.overrides.creativeSettings.catalogItemsboolean
Catalog items.
ad.overrides.creativeSettings.creativeobject
Advantage+ creative enhancements per format (each is opt-in).
ad.overrides.creativeSettings.multiAdvertiserboolean
Multi-advertiser ads.
ad.overrides.creativeSettings.placementCropsstring
Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of off, center
ad.overrides.creativeSettings.productSetIdstring
Product set ID.
ad.overrides.ctastring
Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of Apply now, Book now, Buy now, Buy tickets, Contact us, Donate now, Download, Get offer, Get promotions, Get quote, Get showtimes, Learn more, Listen now, Order now, Play game, Request time, See more, Shop now, Sign up, Subscribe, Watch more, No button
ad.overrides.endCardboolean
false when a carousel has no end card (default true). Meta only.
ad.overrides.identityobject or null
Page and Instagram account IDs; null follows the launch.
ad.overrides.identity.instagramstring
ad.overrides.identity.pagestring
ad.overrides.imageCropsobject
The ad's own crop per shape, in its image's pixels; shapes left out are cropped in the middle while the ad crops.
ad.overrides.imageCrops.1.91:1object
ad.overrides.imageCrops.1:1object
ad.overrides.imageCrops.4:5object
ad.overrides.imageCrops.9:16object
ad.overrides.placementMediaobject
Another image or video per group of placements (feeds, stories, rightColumn), by media library ID; the ad's own file shows everywhere else.
ad.overrides.placementMedia.feedsstring (uuid)
ad.overrides.placementMedia.rightColumnstring (uuid)
ad.overrides.placementMedia.storiesstring (uuid)
ad.overrides.urlstring
Website URL.
ad.statusIdstring (uuid)
Review status.
adSetIdstring (uuid)
The ad set the ads go in; a new one when absent.
adSetNamestring
Without adSetId: the new ad set's name.
adSetSettingsobject
Without adSetId: the new ad set's settings, as POST /launches/{id}/ad-sets takes them.
folderIdstring (uuid)
Every usable file of this folder.
includeUsedboolean
Also make ads of files the launch already has ads of.
kindstring
Folder only: image, video or document.
mediaIdsarray of strings (uuid)
These files, in this order (instead of folderId); 1 to 5,000.
orderstring
Folder only: name (default), oldest or newest.

Response202 Accepted

adSetCreatedbooleanRequired
The ad set was made by this request.
adSetIdstring (uuid)Required
The ad set every ad goes in.
adSetsintegerRequired
Ad sets the ads end up in: 1, the one they go in. Kept for older clients; nothing is split now.
adsintegerRequired
Ads the job makes.
jobIdstring (uuid)Required
The job making the ads.
launchIdstring (uuid)Required
The launch.
skippedobjectRequired
skipped.alreadyInLaunchintegerRequired
Files the launch already uses.
skipped.notUsableintegerRequired
Failed or archived files.
splitSuggestedarray of objects
On Meta, when the ad set will hold more than Meta's usual 50 ads: the split POST /ad-sets/{id}/split makes if wanted. Absent otherwise.
splitSuggested[].adSetIdstring (uuid)Required
The ad set.
splitSuggested[].adsintegerRequired
The ads it will hold.
splitSuggested[].partsintegerRequired
The ad sets a split makes of it, itself included, at most 50 ads each.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/ads/from-media" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 3a10636f-daf4-4e37-a1d7-23c3c1325493" \
  -H "Content-Type: application/json" \
  -d '{
    "ad": {
      "edit": {
        "bestCardsFirst": true,
        "cards": [
          {
            "description": "Two drops every morning for brighter, even skin.",
            "headline": "Brighter skin in 14 days",
            "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
            "url": "https://brevanne.com/products/vitamin-c-serum"
          }
        ],
        "creative": {
          "catalogItems": true,
          "features": {
            "carousel": {
              "description_automation": true,
              "enhance_cta": true,
              "inline_comment": true,
              "profile_card": true,
              "site_extensions": true,
              "text_optimizations": true,
              "text_translation": true
            },
            "image": {
              "adapt_to_placement": true,
              "enhance_cta": true,
              "image_animation": true,
              "image_background_gen": true,
              "image_brightness_and_contrast": true,
              "image_templates": true,
              "image_touchups": true,
              "image_uncrop": true,
              "inline_comment": true,
              "music": true,
              "site_extensions": true,
              "text_optimizations": true,
              "text_translation": true
            },
            "video": {
              "enhance_cta": true,
              "inline_comment": true,
              "site_extensions": true,
              "text_optimizations": true,
              "text_translation": true,
              "video_auto_crop": true,
              "video_filtering": true,
              "video_uncrop": true
            }
          },
          "multiAdvertiser": true,
          "placementCrops": "off",
          "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
        },
        "cta": "Apply now",
        "description": "Two drops every morning for brighter, even skin.",
        "displayLink": "Brevanne",
        "endCard": true,
        "headline": "Brighter skin in 14 days",
        "identity": {
          "instagram": "Brevanne",
          "page": "Brevanne"
        },
        "imageCrops": {
          "1.91:1": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          },
          "1:1": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          },
          "4:5": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          },
          "9:16": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          }
        },
        "placementMedia": {
          "feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
          "rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
          "stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
        },
        "text": "Can we try the 4x5 cut for Instagram feed before we publish?",
        "url": "https://brevanne.com/products/vitamin-c-serum",
        "useLaunch": [
          "copy"
        ],
        "utm": "https://brevanne.com/products/vitamin-c-serum"
      },
      "overrides": {
        "bestCardsFirst": true,
        "cards": [
          {
            "description": "Two drops every morning for brighter, even skin.",
            "headline": "Brighter skin in 14 days",
            "mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
            "url": "https://brevanne.com/products/vitamin-c-serum"
          }
        ],
        "copyVariations": {
          "descriptions": [
            "Two drops every morning for brighter, even skin."
          ],
          "headlines": [
            "Brighter skin in 14 days"
          ],
          "primaryTexts": [
            "Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50."
          ]
        },
        "creativeSettings": {
          "catalogItems": true,
          "creative": {
            "carousel": [
              "text_optimizations"
            ],
            "image": [
              "text_optimizations"
            ],
            "video": [
              "text_optimizations"
            ]
          },
          "multiAdvertiser": true,
          "placementCrops": "off",
          "productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
        },
        "cta": "Apply now",
        "endCard": true,
        "identity": {
          "instagram": "Brevanne",
          "page": "Brevanne"
        },
        "imageCrops": {
          "1.91:1": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          },
          "1:1": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          },
          "4:5": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          },
          "9:16": {
            "height": 1920,
            "width": 1080,
            "x": 3,
            "y": 3
          }
        },
        "placementMedia": {
          "feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
          "rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
          "stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
        },
        "url": "https://brevanne.com/products/vitamin-c-serum"
      },
      "statusId": "069ff91e-35e1-4603-afc3-792b04f09624"
    },
    "adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
    "adSetName": "Broad, United States",
    "adSetSettings": {},
    "folderId": "ab9477f7-881a-493c-a181-28d841376527",
    "includeUsed": true,
    "kind": "image",
    "mediaIds": [
      "04acd56b-ded4-4670-9f9b-1c0c550c1701"
    ],
    "order": "name"
  }'
POST/launches/{id}/archive

Archive or restore a launch

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

archivedboolean
false restores.
expectedVersioninteger
The version you last read. A mismatch is a conflict that returns the current entity.

Response200 OK

adAccountIdstring or null
act_…
archivedAtstring (date-time) or null
Archived.
campaignIdstring or null
The existing Meta campaign it publishes into; null when it creates newCampaign.
copiedFromLaunchIdstring (uuid) or null
The launch it was copied from to this platform.
createdAtstring (date-time)
Created.
externalKeystring or null
Your own key.
groupIdstring (uuid) or null
Its launch group (GET /launch-groups/{id}): the launch's other campaigns are there.
idstring (uuid)Required
ID.
invalidarray of objects
Only in a write's answer: values of the launch kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
invalid[].messagestringRequired
Problem.
labelstring or null
Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
namestring
Name.
newCampaignobject or null
The campaign it creates at publish.
newCampaign.bidStrategystring
Bid strategy.One of LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_BID_CAP, LOWEST_COST_WITH_MIN_ROAS
newCampaign.budgetstring
In the ad account currency; empty until set (a draft's new campaign starts without a budget unless the workspace's campaign defaults have one).
newCampaign.budgetModestring
campaign (Advantage campaign budget) or ad_set.One of campaign, ad_set
newCampaign.budgetPeriodstring
Period.One of daily, lifetime
newCampaign.budgetSharingboolean
Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.namestring
Name.
newCampaign.objectivestring
Meta objective.One of OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_LEADS, OUTCOME_ENGAGEMENT, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION
newCampaign.specialAdCategoriesarray of strings
Special ad categories.
newCampaign.spendCapstring
Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
platformstring
The ad platform it belongs to (meta, or a platform from GET /platforms); fixed at creation.
platformSettingsobject or null
The platform's own launch settings (GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta.
publishJobIdstring (uuid) or null
The latest publish job.
publishedAtstring (date-time) or null
First published.
scheduleAtstring (date-time) or null
When publishing starts.
settingsobject
The launch's settings its ad sets and ads inherit. Meta: all of them. Another platform: only the content every platform shares (primaryTexts, headlines, descriptions, cta, websiteUrl, utm, adNaming, adSetNaming, delivery); its own settings are platformSettings.
sharedWithGuestsboolean
Shared with the workspace's guests for review.
statusstring
Status.One of draft, publishing, published, failed
updatedAtstring (date-time)
Last change.
versioninteger
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/archive" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 7d1af078-3ca8-46ef-846d-edb6c6b2642f" \
  -H "Content-Type: application/json" \
  -d '{
    "archived": false,
    "expectedVersion": 3
  }'
GET/launches/{id}/archived

List a launch's archived ad sets and ads

Ads and ad sets deleted at their ad platform, and ads with comments or activity deleted here, stay as read-only history: hidden from the board, publishing, bulk edits and counts, their comments and activity still readable. Every archived ad set, and a page of archived ads, most recent first.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adSetsarray of objectsRequired
Every archived ad set, most recent first.
adSets[].archivedAtstring (date-time)Required
Archived.
adSets[].archivedByobjectRequired
adSets[].archivedBy.idstring (uuid)Required
Person, API key or agent client.
adSets[].archivedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
adSets[].deletedAtMetabooleanRequired
Deleted at its ad platform: restoring creates a new draft copy.
adSets[].idstring (uuid)Required
ID.
adSets[].namestringRequired
Name.
adSets[].versionintegerRequired
Version.
adsarray of objectsRequired
A page of archived ads, most recent first.
ads[].adSetIdstring (uuid) or nullRequired
ads[].archivedAtstring (date-time)Required
Archived.
ads[].archivedByobjectRequired
ads[].archivedBy.idstring (uuid)Required
Person, API key or agent client.
ads[].archivedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
ads[].commentCountintegerRequired
Comments (not deleted); still readable.
ads[].deletedAtMetabooleanRequired
Deleted at its ad platform: restoring creates a new draft copy.
ads[].idstring (uuid)Required
ID.
ads[].mediaIdstring (uuid) or nullRequired
ads[].namestringRequired
Name.
ads[].versionintegerRequired
Version.
launchIdstring (uuid)Required
Launch.
nextAfterstring or nullRequired
Cursor for the next page of ads; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/archived" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/launches/{id}/campaign/budget

Change the launch's campaign budget

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

amountstringRequired
In the ad account currency.

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or on Meta when its limit of 4 budget changes per ad set per hour allows.
jobIdstring (uuid)Required
The job applying the change.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/campaign/budget" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 38917b61-77c9-49c5-8bcc-ccc3a3d60733" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150.00"
  }'
POST/launches/{id}/campaign/copies

Duplicate a launch's live campaign

A launch's live object by its Pluto ID, copied on the launch's platform: in Meta with Meta's copies (intoAdSetId / intoCampaignId take Meta IDs there); on another platform Pluto reads each object and creates it again: in another ad set or campaign of the same ad account where the platform's own Copy and paste does that (intoAdSetId / intoCampaignId: its IDs, or Pluto IDs of what a launch published), otherwise in the same parent (intoAdSetId and intoCampaignId are refused). Copies start paused unless statusOption says otherwise; deepCopy copies what is inside too. Answers 202 with the job; its items name each copy (output.copiedId), written into the synced lists as soon as it exists and into change history with who asked.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

deepCopyboolean
Ad sets and campaigns: copy what is inside too (default false).
endTimestring (date-time)
Ad sets and campaigns: when the copied ad sets end.
intoAdSetIdstring
Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignIdstring
Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsobject
renameOptions.prefixstring
Put before the name.
renameOptions.strategystring
Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of ONLY_TOP_LEVEL_RENAME, DEEP_RENAME, NO_RENAME
renameOptions.suffixstring
Put after the name (Meta's default is a localized " - Copy").
startTimestring (date-time)
Ad sets and campaigns: when the copied ad sets start.
statusOptionstring
How the copy starts (default PAUSED).One of PAUSED, ACTIVE, INHERITED_FROM_SOURCE

Response202 Accepted

jobIdstring (uuid)Required
The copy job; its items name each copy (output.copiedId).
levelstringRequired
What is copied.One of campaign, ad_set, ad
objectsintegerRequired
How many objects the job copies.
sourceIdstringRequired
The original's ID on its platform.
statusOptionstringRequired
How the copies start.One of PAUSED, ACTIVE, INHERITED_FROM_SOURCE

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/campaign/copies" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 52712647-0ad0-49d3-816f-3abfa08680b4" \
  -H "Content-Type: application/json" \
  -d '{
    "deepCopy": true,
    "endTime": "2026-09-30T13:00:00Z",
    "intoAdSetId": "120240541407845332",
    "intoCampaignId": "120227168091908311",
    "renameOptions": {
      "prefix": "Fall - ",
      "strategy": "ONLY_TOP_LEVEL_RENAME",
      "suffix": " - Copy"
    },
    "startTime": "2026-09-30T13:00:00Z",
    "statusOption": "PAUSED"
  }'
PATCH/launches/{id}/campaign/dates

Change the launch's campaign dates

FINANCIAL. For a platform that schedules the campaign, not its ad sets: changes the first and last day the launch's live campaign runs, in the ad account's time zone. A key left out stays as it is; end: null lets the campaign run on. A campaign that already started keeps its start date, a day in the past is refused, the end is never before the start, and a campaign with a total budget keeps an end date (422 on startDate or endDate). The platform checks the change before it is queued. A launch whose platform schedules its ad sets answers 404: use PATCH /ad-sets/{id}/schedule there.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

endstring (date) or null
The last day it runs (YYYY-MM-DD); null lets it run on.
startstring (date)
The first day it runs (YYYY-MM-DD); only for a campaign that hasn't started.

Response202 Accepted

availableAtstring (date-time)Required
When it runs.
jobIdstring (uuid)Required
The job applying the change; follow it with GET /jobs/{id}.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404No such launch, or its platform schedules its ad sets.
  • 409The launch isn't live.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/campaign/dates" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 4c305f71-515c-4fd3-9731-69674857f3c6" \
  -H "Content-Type: application/json" \
  -d '{
    "end": "2026-09-27",
    "start": "2026-09-01"
  }'
POST/launches/{id}/campaign/remove

Remove the launch's live campaign

FINANCIAL, cannot be undone. For a platform that removes campaigns: removes the launch's live campaign at the platform, where it stops for good and stays readable; then the launch is archived, its results, history and comments kept. Where the platform deletes a campaign with its ad sets and ads instead, each is deleted there for good and archived in the launch. Where the platform's rules say so, only a person asks for this (an agent, a loop or a key gets 403; an agent's approval card runs as the person who approves). Send expectedVersion from the last read of the launch. A launch whose platform pauses campaigns instead answers 404.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

expectedVersioninteger
The launch's version last read.

Response202 Accepted

deletesarray of objectsRequired
What the job removes at the platform.
deletes[].entitystring
deletes[].idstring (uuid)
deletes[].providerIdstring
jobIdstring (uuid)Required
The job removing it; follow it with GET /jobs/{id}.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403Only a person removes a campaign, or the caller can't delete.
  • 404No such launch, or its platform doesn't remove campaigns.
  • 409The campaign isn't live, the launch changed or is publishing, or the ad account is read-only.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/campaign/remove" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 5e015e1f-90b9-4026-bc6a-bf823f4a4042" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3
  }'
PATCH/launches/{id}/campaign/shared-budget

Change the launch's shared budget

FINANCIAL. For a platform where several campaigns can run on one budget: changes the amount of the budget the launch's live campaign runs on, which changes every campaign on it. Nothing is sent until the caller names all of them: PATCH /launches/{id}/campaign/budget on such a launch answers 409 with sharedBudget and campaigns, read from the platform then; confirm the list with whoever decides, and send every campaign's id here as campaignIds. If the campaigns on the budget are no longer exactly those, the answer is 409 with the current list and nothing changes. The platform checks the change before it is queued (422 on amount in its own words); the answer and the audit log name every campaign it reached. A launch whose platform has no shared budgets answers 404; a campaign with a budget of its own answers 409.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

amountstringRequired
The budget's new amount, in the ad account's currency.
campaignIdsarray of stringsRequired
Every campaign on the budget, as the 409 of PATCH /launches/{id}/campaign/budget listed them.

Response202 Accepted

availableAtstring (date-time)Required
When it runs.
campaignsarray of objectsRequired
Every campaign the change reaches.
campaigns[].idstringRequired
The platform's ID.
campaigns[].namestringRequired
Its name at the platform.
jobIdstring (uuid)Required
The job applying the change; follow it with GET /jobs/{id}.
sharedBudgetobjectRequired
The budget that changes.
sharedBudget.idstringRequired
The platform's ID.
sharedBudget.namestringRequired
Its name at the platform.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404No such launch, or its platform has no shared budgets.
  • 409The campaigns on the budget aren't the ones named (the body carries sharedBudget and campaigns), the campaign has a budget of its own, or the launch isn't live.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/campaign/shared-budget" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 1e39a353-99dd-4731-95d1-60af2edc6d05" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150.00",
    "campaignIds": [
      "120227168091908311"
    ]
  }'
POST/launches/{id}/campaign/status

Pause or activate the launch's campaign

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

statusstringRequired
Delivery.One of ACTIVE, PAUSED

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or on Meta when its limit of 4 budget changes per ad set per hour allows.
jobIdstring (uuid)Required
The job applying the change.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/campaign/status" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 03d06b96-927c-4fc6-89cf-70d1935c373d" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACTIVE"
  }'
PATCH/launches/{id}/campaign/targets

Change the launch's bidding targets

FINANCIAL. For a platform that bids on the campaign: changes the targets of the launch's live campaign, each where its bid strategy takes it: the cost per action to aim for, the return on ad spend to aim for, the most a click may cost, and an impression share target. A key left out stays as it is; an empty text clears that target. The platform checks the change before it is queued (422 on the field in its own words); the launch's own settings follow, so the change isn't offered again as a pending change. The bid strategy itself is changed in the launch's platformSettings and published with its other changes (POST /launches/{id}/revisions/publish). A campaign that follows a bid strategy shared with other campaigns answers 409: its targets are that strategy's. A launch whose platform keeps no bidding on the campaign answers 404.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

impressionShareobject
An impression share target: where on the results page, how much, and at what limit.
impressionShare.locationstringRequired
Where on the results page the ads should show.One of ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE
impressionShare.maxCpcstring
The most a click may cost, a decimal in the ad account's currency.
impressionShare.percentstring
Percent of impressions to aim for, 1 to 100.
maxCpcstring
The most a click may cost, a decimal in the ad account's currency; "" clears it.
targetCpastring
The cost per action to aim for, a decimal in the ad account's currency; "" clears it.
targetRoasstring
The return on ad spend to aim for, in percent ("350" is 350%); "" clears it.

Response202 Accepted

availableAtstring (date-time)Required
When it runs.
jobIdstring (uuid)Required
The job applying the change; follow it with GET /jobs/{id}.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404No such launch, or its platform keeps no bidding targets on the campaign.
  • 409The campaign follows a bid strategy shared with other campaigns, or the launch isn't live.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/campaign/targets" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 12fad2c3-caec-44fc-bdce-0040abb8fb00" \
  -H "Content-Type: application/json" \
  -d '{
    "impressionShare": {
      "location": "ANYWHERE_ON_PAGE",
      "maxCpc": "150.00",
      "percent": "20"
    },
    "maxCpc": "150.00",
    "targetCpa": "150.00",
    "targetRoas": "2.84"
  }'
POST/launches/{id}/duplicate

Duplicate a launch

A new launch: a draft on the same platform with the same destination, settings, ad sets and ads; ads restart at the default review status. With platform (another platform from GET /platforms) and adAccountId there, it copies the launch to that platform instead and the copy joins the launch's group as another campaign (groupId, as POST /launch-groups/{id}/campaigns with from adds one, its ads linked to their originals): ad sets, ads with their media, copy, link, a button that platform offers, the objective and budgets (only between ad accounts of one currency) carry over in its own fields, what it needs beyond that comes from its defaults, and the rest is left out; the copy keeps copiedFromLaunchId. dryRun: true answers that plan without copying (200): copied (with what each carries in detail), defaults (with value, and replaces when it takes the place of the source's own) and skipped (with the reason), each with its label.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adAccountIdstring
The ad account on that platform.
dryRunboolean
Answer the plan without copying.
namestring
Name; defaults to "<name> copy" (on another platform, the name the launch group's naming rule gives it).
platformstring
Copy to this platform as another campaign of the launch (default: the launch's own, a new launch).

Response200 OK

codestringRequired
Stable code.One of bad_request, unauthenticated, forbidden, not_found, conflict, invalid, rate_limited, unavailable, internal
currentobject
The current entity, on a stale expectedVersion (409).
errorsarray of objects
Every field problem (422).
errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
errors[].fieldstringRequired
JSON-pointer-like path.
errors[].messagestringRequired
Problem.
errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
requestIdstring
The request's ID, as in the x-request-id header. Include it when you report a problem.
statusintegerRequired
HTTP status.
titlestringRequired
What went wrong, for the person or agent reading it.
titleCodestring
A registered title's stable code (such as not_found_the_launch), for an app to say the title in its language; absent for a title without one. title reads the same either way.
titleParamsobject
The values titleCode's sentence names, present exactly when titleCode is.
traceIdstring
The request's trace ID, as in the x-trace-id header.
typestringRequired
Documentation URL for code.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/duplicate" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 9960a3d8-a02a-4abb-8e4d-2ae76261a652" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_741877585619437",
    "dryRun": false,
    "name": "Fall launch",
    "platform": "Brevanne"
  }'
GET/launches/{id}/publication

Get what's published

Published objects and their status.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

launchId, phase (draft, scheduled, publishing, published, partially_published, failed), jobId, counts and every published object with its ID on the platform (providerId), configured and effective status, review feedback and errors. Per object: error (why it wasn't created) and changeError (the last live change the platform refused), both {code, field, metaField, message} with field the API path to fix (code invalid adds title and userMessage, Meta's own title and words for the person, each null when Meta gave none; changeError also names its jobId; codes action_in_meta and refused add next, the person's next step as one sentence, and action_in_meta adds need; code reauthorize adds reason (expired or permission) and permission (the missing Meta permission or null); code account_unavailable means the ad account can't take new ads; messageCode and messageParams, beside a message in Pluto's own words, are its stable code (such as publish_ad_set_not_created) and values, for an app to say it in its language); budget — the platform's current budget from readback as {amount (decimal string), period (daily, lifetime or total), currency}, null until read back or without a budget of its own; parent — an ad's ad set or an ad set's campaign as {entity, id (ours; null for an existing campaign), providerId}; managedInMeta — for objects imported from Meta, the values Pluto can't represent as [{field, metaField, reason}] (read-only, never written back). origin is published or imported. progress (null before the first publish) — the latest publish in numbers: stage, adSets/ads/media as {created, failed, total}, waiting {reason, until, kind} (the platform's limits, video processing, a retry), failures [{entity, id, state, code, message, messageCode?, messageParams?, field}], held (created but kept paused, with why: [{entity, id, reason, reasonCode?, reasonParams?}]) and reconciled ({checked, adopted, strays, missing}). Ad sets and ads someone made in Meta that Keep in sync brought in carry sourceApp (the app they were made in, e.g. Ads Manager; null for Pluto's own); syncedAt says when Keep in sync last brought the launch in line, null when it doesn't keep it in sync. notImported ({total, items [{entity, metaId, name, reason}]}, at most 200 items) is what of its campaign Keep in sync left in Meta and why (an ad without an image or video Pluto can copy, a kind of ad Pluto can't hold); null when everything came in or it isn't kept in sync. Ad sets with pins carry placedPins [{list (places or excludedPlaces), index (among that list's pins), address (Meta's own normalized text, or null), latitude, longitude}]: where Meta placed each one, as first read after publishing.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/publication" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/launches/{id}/publish

Preview a publish

What a publish would do, and what blocks it.

Returns what an approval must echo: launchVersion, adAccountId and budgetSummary.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstring or null
act_…
budgetChangesarray of objectsRequired
Live ad sets whose budget changes, e.g. after a split divided it.
budgetChanges[].adSetIdstring (uuid)Required
A live ad set.
budgetChanges[].livestringRequired
The budget running at Meta now (decimal).
budgetChanges[].pendingstringRequired
The budget after publishing (decimal).
budgetChanges[].periodstringRequired
daily or lifetime.
budgetSummaryobject or nullRequired
Echo exactly in the approval; null until ready.
budgetSummary.adSetsarray of objectsRequired
Ad set budgets.
budgetSummary.adSets[].adSetIdstring (uuid)Required
Ad set.
budgetSummary.adSets[].amountstringRequired
In the ad account currency.
budgetSummary.adSets[].periodstringRequired
Period.One of daily, lifetime
budgetSummary.campaignobject or nullRequired
The new campaign's budget (Advantage campaign budget); null with ad set budgets or an existing campaign.
budgetSummary.campaign.amountstringRequired
In the ad account currency.
budgetSummary.campaign.periodstringRequired
Period.One of daily, lifetime
budgetSummary.currencystringRequired
ISO 4217 currency of every amount.
budgetSummary.dailyTotalstring or nullRequired
Sum of daily budgets; null when there are none.
budgetSummary.lifetimeTotalstring or nullRequired
Sum of lifetime budgets; null when there are none.
createPathstring
On a platform whose create path depends on the ad account: smart_plus (its automated campaign type) or manual. Absent when the platform creates no such campaign now (the checklist says why), when publishing into an existing campaign, and on platforms with one create path.
createsobjectRequired
creates.adSetsintegerRequired
Ad sets.
creates.adsintegerRequired
Ads.
creates.campaignsintegerRequired
Campaigns.
creates.mediaintegerRequired
Media uploads.
currencystring or null
ISO 4217 of the ad account.
excludedobjectRequired
excluded.emptyAdSetsarray of objectsRequired
Ad sets without creatives. Meta delivers only through ads, so they aren't created (nor their budget approved) until they have one.
excluded.emptyAdSets[].idstring (uuid)Required
Ad set.
excluded.emptyAdSets[].namestringRequired
Name.
excluded.ungroupedAdIdsarray of strings (uuid)Required
Their IDs, in board order.
excluded.ungroupedAdsintegerRequired
Creatives in Ungrouped. They are drafts: not published, not counted in creates or the budget, and their gaps don't block publishing.
itemsarray of objectsRequired
The checklist plus publishing's own checks.
items[].actionstring
A one-step fix: split_ad_set runs POST /ad-sets/{id}/split on adSetId.
items[].adIdstring
The ad it concerns.
items[].adNamestring
Its name.
items[].adSetstring
The ad set it concerns, by name.
items[].adSetIdstring
The ad set's ID.
items[].fieldstringRequired
Where the person fixes it, as the app names the place (Ad account, Campaign, Headline, Ad set settings, Ad sets, Launch settings): a label to show, the same kind on every platform. Never a path; match, focus or route on path.
items[].idstringRequired
Stable item ID.
items[].labelstringRequired
Short label.
items[].labelCodestring
A registered label's stable code (such as review_match_campaign_objective), for an app to say it in its language; absent when the label is free text.
items[].labelParamsobject
The values labelCode's sentence names, present exactly when it names any.
items[].labelPlaceobject
The one text a coded label is said of, apart from its sentence so an app says both in its language: { field (headline, description, keyword or negativeKeyword), index (1-based) } (a platform's check on an ad's third headline: headline, 3). Absent when the label names no place or holds it as free text; label keeps it in English.
items[].messagestringRequired
What to fix.
items[].nextCodestring
The next step's stable code when message is a registered next step (a platform's own check), for an app to say it under the label in its language; absent otherwise.
items[].nextParamsobject
The values nextCode's sentence names, present exactly when it names any.
items[].nextTopicsstring
The policy topics the platform names beside the next step, in its own words (TRADEMARKS, ALCOHOL), present with nextCode when it names any.
items[].pathstring or nullRequired
The API path of the value to fix, on every platform: on the launch (adAccountId, settings.page, newCampaign.budget, platformSettings.campaign.objective), the ad set in adSetId (targeting.countries, overrides.beneficiary, platformSettings.costType) or the ad in adId (overrides.url), as in publishing errors' field. What to match, focus or route on. Null when the fix isn't a field: connect Meta, add creatives, or move creatives into an ad set.
launchIdstring (uuid)Required
Launch.
launchVersionintegerRequired
Approve this exact version.
readybooleanRequired
Nothing is in the way.
scheduleAtstring (date-time) or null
Scheduled start.
smartPlusAccessobject
smartPlusAccess.learnedAtstring (date-time) or nullRequired
When Pluto learned it.
smartPlusAccess.manualUntilstringRequired
The last day the platform creates manual campaigns (a date).
smartPlusAccess.statusstringRequired
yes, no or unknown (not tried yet).
statusstringRequired
Launch status.
timezonestring or null
IANA time zone of the ad account.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/publish" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/launches/{id}/publish

Publish a launch

Re-checks readiness and binds the approval to the concrete launch version, ad account and budgets; any change since is a 409 whose current is the approval to review. A launch that isn't ready is a 409 with the checklist in items (same shape as the preview's). Nothing reads as live before readback.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

approvalobjectRequired
approval.adAccountIdstringRequired
The ad account, as the preview gave it.
approval.budgetSummaryobjectRequired
approval.budgetSummary.adSetsarray of objectsRequired
Ad set budgets.
approval.budgetSummary.adSets[].adSetIdstring (uuid)Required
Ad set.
approval.budgetSummary.adSets[].amountstringRequired
In the ad account currency.
approval.budgetSummary.adSets[].periodstringRequired
Period.One of daily, lifetime
approval.budgetSummary.campaignobject or nullRequired
The new campaign's budget (Advantage campaign budget); null with ad set budgets or an existing campaign.
approval.budgetSummary.campaign.amountstringRequired
In the ad account currency.
approval.budgetSummary.campaign.periodstringRequired
Period.One of daily, lifetime
approval.budgetSummary.currencystringRequired
ISO 4217 currency of every amount.
approval.budgetSummary.dailyTotalstring or nullRequired
Sum of daily budgets; null when there are none.
approval.budgetSummary.lifetimeTotalstring or nullRequired
Sum of lifetime budgets; null when there are none.
approval.launchVersionintegerRequired
Version.
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.

Response202 Accepted

jobIdstring (uuid)Required
The publish job.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/publish" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 560294a2-d3c8-467b-85d4-df4597d5c1ef" \
  -H "Content-Type: application/json" \
  -d '{
    "approval": {
      "adAccountId": "act_741877585619437",
      "budgetSummary": {
        "adSets": [
          {
            "adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
            "amount": "150.00",
            "period": "daily"
          }
        ],
        "campaign": {
          "amount": "150.00",
          "period": "daily"
        },
        "currency": "USD",
        "dailyTotal": "150.00",
        "lifetimeTotal": "150.00"
      },
      "launchVersion": 3
    },
    "expectedVersion": 3
  }'
POST/launches/{id}/publish/cancel

Stop a publish that hasn't finished

Objects already created on the platform stay live.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

launchId, phase (draft, scheduled, publishing, published, partially_published, failed), jobId, counts and every published object with its ID on the platform (providerId), configured and effective status, review feedback and errors. Per object: error (why it wasn't created) and changeError (the last live change the platform refused), both {code, field, metaField, message} with field the API path to fix (code invalid adds title and userMessage, Meta's own title and words for the person, each null when Meta gave none; changeError also names its jobId; codes action_in_meta and refused add next, the person's next step as one sentence, and action_in_meta adds need; code reauthorize adds reason (expired or permission) and permission (the missing Meta permission or null); code account_unavailable means the ad account can't take new ads; messageCode and messageParams, beside a message in Pluto's own words, are its stable code (such as publish_ad_set_not_created) and values, for an app to say it in its language); budget — the platform's current budget from readback as {amount (decimal string), period (daily, lifetime or total), currency}, null until read back or without a budget of its own; parent — an ad's ad set or an ad set's campaign as {entity, id (ours; null for an existing campaign), providerId}; managedInMeta — for objects imported from Meta, the values Pluto can't represent as [{field, metaField, reason}] (read-only, never written back). origin is published or imported. progress (null before the first publish) — the latest publish in numbers: stage, adSets/ads/media as {created, failed, total}, waiting {reason, until, kind} (the platform's limits, video processing, a retry), failures [{entity, id, state, code, message, messageCode?, messageParams?, field}], held (created but kept paused, with why: [{entity, id, reason, reasonCode?, reasonParams?}]) and reconciled ({checked, adopted, strays, missing}). Ad sets and ads someone made in Meta that Keep in sync brought in carry sourceApp (the app they were made in, e.g. Ads Manager; null for Pluto's own); syncedAt says when Keep in sync last brought the launch in line, null when it doesn't keep it in sync. notImported ({total, items [{entity, metaId, name, reason}]}, at most 200 items) is what of its campaign Keep in sync left in Meta and why (an ad without an image or video Pluto can copy, a kind of ad Pluto can't hold); null when everything came in or it isn't kept in sync. Ad sets with pins carry placedPins [{list (places or excludedPlaces), index (among that list's pins), address (Meta's own normalized text, or null), latitude, longitude}]: where Meta placed each one, as first read after publishing.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/publish/cancel" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: a38bf51d-ea8e-4e17-afda-7b28bc56b2ac"
POST/launches/{id}/readback

Read a launch back from its ad platform

Read published objects back from the launch's ad platform now.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response202 Accepted

jobIdstring (uuid)Required
The readback job.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/readback" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/launches/{id}/review

Get the readiness checklist

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

excludedobjectRequired
excluded.emptyAdSetsarray of objectsRequired
Ad sets without creatives. Meta delivers only through ads, so they aren't created (nor their budget approved) until they have one.
excluded.emptyAdSets[].idstring (uuid)Required
Ad set.
excluded.emptyAdSets[].namestringRequired
Name.
excluded.ungroupedAdIdsarray of strings (uuid)Required
Their IDs, in board order.
excluded.ungroupedAdsintegerRequired
Creatives in Ungrouped. They are drafts: not published, not counted in creates or the budget, and their gaps don't block publishing.
itemsarray of objectsRequired
What still blocks publishing: only ad sets with creatives and the ads in them are checked.
items[].actionstring
A one-step fix: split_ad_set runs POST /ad-sets/{id}/split on adSetId.
items[].adIdstring
The ad it concerns.
items[].adNamestring
Its name.
items[].adSetstring
The ad set it concerns, by name.
items[].adSetIdstring
The ad set's ID.
items[].fieldstringRequired
Where the person fixes it, as the app names the place (Ad account, Campaign, Headline, Ad set settings, Ad sets, Launch settings): a label to show, the same kind on every platform. Never a path; match, focus or route on path.
items[].idstringRequired
Stable item ID.
items[].labelstringRequired
Short label.
items[].labelCodestring
A registered label's stable code (such as review_match_campaign_objective), for an app to say it in its language; absent when the label is free text.
items[].labelParamsobject
The values labelCode's sentence names, present exactly when it names any.
items[].labelPlaceobject
The one text a coded label is said of, apart from its sentence so an app says both in its language: { field (headline, description, keyword or negativeKeyword), index (1-based) } (a platform's check on an ad's third headline: headline, 3). Absent when the label names no place or holds it as free text; label keeps it in English.
items[].messagestringRequired
What to fix.
items[].nextCodestring
The next step's stable code when message is a registered next step (a platform's own check), for an app to say it under the label in its language; absent otherwise.
items[].nextParamsobject
The values nextCode's sentence names, present exactly when it names any.
items[].nextTopicsstring
The policy topics the platform names beside the next step, in its own words (TRADEMARKS, ALCOHOL), present with nextCode when it names any.
items[].pathstring or nullRequired
The API path of the value to fix, on every platform: on the launch (adAccountId, settings.page, newCampaign.budget, platformSettings.campaign.objective), the ad set in adSetId (targeting.countries, overrides.beneficiary, platformSettings.costType) or the ad in adId (overrides.url), as in publishing errors' field. What to match, focus or route on. Null when the fix isn't a field: connect Meta, add creatives, or move creatives into an ad set.
readybooleanRequired
No checklist items remain.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/review" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/launches/{id}/revisions

List pending changes

Pending changes to published objects.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

revisionsVersion, currency (the publication's: budget and bid amounts are decimal strings in it) and, per object and field, the live and pending value, whether the platform can change it, whether it sends ads back to review (review) and, on Meta, whether it restarts the learning phase (learning: targeting, creative, optimization and bid strategy changes, and budget, bid or ROAS goal changes of 50% or more). Each object has a version, its parent, reviewAds, learningAdSets and revertable; each change a version. counts sorts every change once: selectable (can be chosen and published now), needsChoice (changed at the platform since: publish over it or discard), locked (the platform can't make it, or the object is gone there; it waits until discarded) and publishing. impact counts ads back to review and, on Meta, ad sets restarting learning for every change; applying is the progress of changes being sent ({jobId, campaign, adSets, ads} with done, failed and total). unpublished lists draft ad sets and ads publishing again creates (not creatives in Ungrouped or ad sets without creatives). On Meta, a change with conflict wasn't sent because Meta's value changed since it was published (in Ads Manager): {metaValue, metaVersion, changedAt, changedBy}; discard it to keep Meta's value, or publish it with changes[].overwrite = metaVersion; deletedInMeta marks an object deleted in Ads Manager: never created again, its changes can only be discarded. A change's error ({code, field, metaField, message}) adds messageCode and messageParams when message is in Pluto's own words: its stable code and values, for an app to say it in its language. lastPublish is what the latest publish of pending changes did, per change ({jobId, finished, counts, results}; each result published, publishing, waiting or failed with reason), null before the first.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/revisions" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/launches/{id}/revisions/discard

Discard pending changes

revisionsVersion returns the whole launch to the live version; changes reverts only those objects or fields. A field that follows the launch settings can't be reverted on its own (409). On Meta, a change with a conflict keeps Meta's value instead: it becomes the live version and the draft.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

changesarray of objects
Only these changes; the rest stay pending. A change edited since it was read is a 409 naming it in stale, with the current revisionsVersion.
changes[].fieldstring
Optional: one field of it; omit for every change of the object.
changes[].idstring (uuid)Required
The object: the launch ID for its campaign, an ad set or an ad.
changes[].versionstringRequired
The change's version with field, the object's version without.
revisionsVersionstring
From GET /launches/{id}/revisions: every pending change. Omit when sending changes.

Response200 OK

The revisions.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/revisions/discard" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 0421cc15-847c-4fb8-be02-ce7dd8553bed" \
  -H "Content-Type: application/json" \
  -d '{
    "changes": [
      {
        "field": "headline",
        "id": "2046ac37-4775-4757-9ef2-3d948cbfc560",
        "version": "version"
      }
    ],
    "revisionsVersion": "changes"
  }'
POST/launches/{id}/revisions/publish

Apply pending changes

Send revisionsVersion for every change, or changes for only some. Every change that can go goes: one the platform won't make now (a value it freezes on a live object, a draft problem, on Meta a value changed in Ads Manager) waits with why and never stops the rest, and an object's budget and bid changes go together or wait together. When nothing can go the answer is 409 with results and counts. On Meta, each changed object is read at Meta once before sending: a value changed there since it was published isn't overwritten (the change gets a conflict) unless its changes[] item carries overwrite with that conflict's metaVersion. Sending the same request again with the same Idempotency-Key never sends a published change twice: it brings results up to date and publishes what waited or didn't publish, if it's still exactly the change approved and can go now.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

changesarray of objects
Only these changes; the rest stay pending. A change edited since it was read is a 409 naming it in stale, with the current revisionsVersion.
changes[].fieldstring
Optional: one field of it; omit for every change of the object.
changes[].idstring (uuid)Required
The object: the launch ID for its campaign, an ad set or an ad.
changes[].versionstringRequired
The change's version with field, the object's version without.
revisionsVersionstring
From GET /launches/{id}/revisions: every pending change. Omit when sending changes.

Response202 Accepted

jobId, queued changes, blocked ones, impact (backToReview ads, and on Meta restartsLearning ad sets) and results: per change {entity, id, name, field, status, reason, fixField, availableAt, jobId}, status being publishing or waiting (with reason and its next step), with counts. The job turns publishing into published or failed: GET /launches/{id}/revisions → lastPublish.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/launches/2046ac37-4775-4757-9ef2-3d948cbfc560/revisions/publish" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 19de6567-c3dc-4578-9f34-947aa9405df8" \
  -H "Content-Type: application/json" \
  -d '{
    "changes": [
      {
        "field": "headline",
        "id": "2046ac37-4775-4757-9ef2-3d948cbfc560",
        "version": "version"
      }
    ],
    "revisionsVersion": "changes"
  }'