Launches
Create, edit and publish launches: batches of ad sets and ads for a Meta or LinkedIn or X ad account.
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Optional | Launch status: draft, publishing, published or failed, several comma-separated. |
adAccountId | string | Optional | Ad account, several comma-separated. |
sort | string | Optional | The order: updated (default), created, published, archived, name, status (draft, publishing, published, failed) or ads. |
dir | string | Optional | asc 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. |
platform | string | Optional | Only launches on this ad platform (meta, or one from GET /platforms). |
q | string | Optional | Search. |
archived | string | Optional | Include archived. |
groupId | string | Optional | Only the campaigns of this launch group (GET /launch-groups/{id}). |
liveness | string | Optional | Only 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. |
after | string | Optional | Cursor. |
limit | string | Optional | Page size. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].adAccountId- act_…
items[].adCount- Ads.
items[].adSetCount- Ad sets.
items[].approvedCount- Ads in a completed (approved) review status.
items[].archivedAt- Archived.
items[].campaignId- Existing campaign.
items[].createdAt- Created.
items[].externalKey- Your own key.
items[].groupId- Its launch group.
items[].groupName- Its launch group's own name.
items[].id- ID.
items[].label- Its own name in its launch group when a person gave one.
items[].liveness- 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[].name- Name.
items[].newCampaignName- The new campaign's name.
items[].platform- The ad platform it belongs to.
items[].previewMediaIds- Processed media of the first four ads that have one, for thumbnails. Media still uploading or processing is left out.
items[].publishedAt- First published.
items[].scheduleAt- Start.
items[].status- Status.
items[].updatedAt- Last change.
items[].version- Increments on every change; send as
expectedVersion. nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/launches" \
-H "Authorization: Bearer $PLUTO_KEY"Create a launch
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
adAccountId- The ad account it publishes to (Meta's: act_…).
campaignId- Existing campaign.
campaignTemplateId- Start the new campaign from this campaign template (over the campaign defaults; keys in
newCampaignstill win). externalKey- Your own key for this launch.
name- Name.
newCampaign- 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.bidStrategy- 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.budget- Campaign budget (budgetMode campaign) as a decimal string in the ad account's currency ("100", "99.50"). Never guessed: ask when unknown.
newCampaign.budgetMode- 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.budgetPeriod- With a campaign budget: daily, or lifetime (spent over the schedule; ad sets need an end).One of
daily,lifetime newCampaign.budgetSharing- With ad set budgets: let ad sets share up to 20% of their budget with better-performing ad sets.
newCampaign.name- Campaign name, up to 400 characters.
newCampaign.objective- 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.specialAdCategories- 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.specialAdCategoryCountry- 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.spendCap- 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.
platform- 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) a422names the choice. platformSettings- A launch on a platform with its own launch settings (
GET /platforms/{platform}/spec,contentnot null):{campaign: {…}, adSet: {…}}with that spec's fields. Not for Meta. scheduleAt- Start time.
settings- 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.adNaming- Ad name pattern: {{asset.name}}, {{campaign.name}}, {{index}}, {{date}} (the ad account's day) and text.
settings.adSetNaming- Ad set name pattern, like adNaming; "" names new ad sets "Ad set N".
settings.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. settings.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
settings.catalogItems- Show products from your catalog (needs productSetId).
settings.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days settings.conversionEvent- 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.creative- Advantage+ creative enhancements per format (each is opt-in).
settings.creative.carousel- 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.image- 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.video- 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.cta- 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.customConversion- 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.delivery- 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.descriptions- Description. Keep one non-empty value.
settings.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day settings.headlines- Headline. Keep one non-empty value.
settings.instagram- Instagram account ads publish as: its Meta ID (get_meta_integration); usually the one linked to the Page. "" uses the Page.
settings.multiAdvertiser- Multi-advertiser ads: the ad can appear alongside other businesses' ads.
settings.page- 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.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
settings.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
settings.placementCrops- 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.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
settings.primaryTexts- Primary text. Publishing sends one per ad: keep one non-empty value.
settings.productSetId- Catalog product set: its numeric Meta ID.
settings.utm- 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.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day settings.websiteUrl- Website URL ads link to (https://…).
Response
adAccountId- act_…
archivedAt- Archived.
campaignId- The existing Meta campaign it publishes into; null when it creates
newCampaign. copiedFromLaunchId- The launch it was copied from to this platform.
createdAt- Created.
externalKey- Your own key.
groupId- Its launch group (
GET /launch-groups/{id}): the launch's other campaigns are there. id- ID.
invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
invalid[].message- Problem.
label- Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
name- Name.
newCampaign- The campaign it creates at publish.
newCampaign.bidStrategy- Bid strategy.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS newCampaign.budget- 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.budgetModecampaign(Advantage campaign budget) orad_set.One ofcampaign,ad_setnewCampaign.budgetPeriod- Period.One of
daily,lifetime newCampaign.budgetSharing- Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.name- Name.
newCampaign.objective- Meta objective.One of
OUTCOME_SALES,OUTCOME_TRAFFIC,OUTCOME_LEADS,OUTCOME_ENGAGEMENT,OUTCOME_AWARENESS,OUTCOME_APP_PROMOTION newCampaign.specialAdCategories- Special ad categories.
newCampaign.spendCap- Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
platform- The ad platform it belongs to (
meta, or a platform fromGET /platforms); fixed at creation. platformSettings- The platform's own launch settings (
GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta. publishJobId- The latest publish job.
publishedAt- First published.
scheduleAt- When publishing starts.
settings- 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 areplatformSettings. sharedWithGuests- Shared with the workspace's guests for review.
status- Status.One of
draft,publishing,published,failed updatedAt- Last change.
version- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}
}'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).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
items- Launches.
items[].adAccountId- act_…
items[].campaignId- Existing campaign.
items[].commandId- This item's command ID.
items[].externalKey- Your own key for this launch.
items[].name- Name.
items[].newCampaign- 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.bidStrategy- 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.budget- Campaign budget (budgetMode campaign) as a decimal string in the ad account's currency ("100", "99.50"). Never guessed: ask when unknown.
items[].newCampaign.budgetMode- 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.budgetPeriod- With a campaign budget: daily, or lifetime (spent over the schedule; ad sets need an end).One of
daily,lifetime items[].newCampaign.budgetSharing- With ad set budgets: let ad sets share up to 20% of their budget with better-performing ad sets.
items[].newCampaign.name- Campaign name, up to 400 characters.
items[].newCampaign.objective- 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.specialAdCategories- 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.specialAdCategoryCountry- 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.spendCap- 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[].platform- A platform from
GET /platforms; left out, as forPOST /launches. items[].platformSettings- The platform's own launch settings (not for Meta).
items[].scheduleAt- Start time.
items[].settings- 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.adNaming- Ad name pattern: {{asset.name}}, {{campaign.name}}, {{index}}, {{date}} (the ad account's day) and text.
items[].settings.adSetNaming- Ad set name pattern, like adNaming; "" names new ad sets "Ad set N".
items[].settings.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. items[].settings.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].settings.catalogItems- Show products from your catalog (needs productSetId).
items[].settings.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days items[].settings.conversionEvent- 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.creative- Advantage+ creative enhancements per format (each is opt-in).
items[].settings.creative.carousel- 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.image- 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.video- 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.cta- 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.customConversion- 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.delivery- 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.descriptions- Description. Keep one non-empty value.
items[].settings.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day items[].settings.headlines- Headline. Keep one non-empty value.
items[].settings.instagram- Instagram account ads publish as: its Meta ID (get_meta_integration); usually the one linked to the Page. "" uses the Page.
items[].settings.multiAdvertiser- Multi-advertiser ads: the ad can appear alongside other businesses' ads.
items[].settings.page- 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.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].settings.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].settings.placementCrops- 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.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
items[].settings.primaryTexts- Primary text. Publishing sends one per ad: keep one non-empty value.
items[].settings.productSetId- Catalog product set: its numeric Meta ID.
items[].settings.utm- 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.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day items[].settings.websiteUrl- Website URL ads link to (https://…).
Response
items- One outcome per item, in order:
launchwhen accepted;errorswhen rejected (acommandIdreused for other input is rejected oncommandId);messageon a conflict. items[].commandId- The item's command ID.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].launch- A launch: one batch of ads for a provider ad account.
items[].launch.adAccountId- act_…
items[].launch.archivedAt- Archived.
items[].launch.campaignId- The existing Meta campaign it publishes into; null when it creates
newCampaign. items[].launch.copiedFromLaunchId- The launch it was copied from to this platform.
items[].launch.createdAt- Created.
items[].launch.externalKey- Your own key.
items[].launch.groupId- Its launch group (
GET /launch-groups/{id}): the launch's other campaigns are there. items[].launch.id- ID.
items[].launch.invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
items[].launch.invalid[].message- Problem.
items[].launch.label- 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.name- Name.
items[].launch.newCampaign- The campaign it creates at publish.
items[].launch.newCampaign.bidStrategy- Bid strategy.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS items[].launch.newCampaign.budget- 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.budgetModecampaign(Advantage campaign budget) orad_set.One ofcampaign,ad_setitems[].launch.newCampaign.budgetPeriod- Period.One of
daily,lifetime items[].launch.newCampaign.budgetSharing- Ad sets share up to 20% of their budget (ad set budgets only).
items[].launch.newCampaign.name- Name.
items[].launch.newCampaign.objective- Meta objective.One of
OUTCOME_SALES,OUTCOME_TRAFFIC,OUTCOME_LEADS,OUTCOME_ENGAGEMENT,OUTCOME_AWARENESS,OUTCOME_APP_PROMOTION items[].launch.newCampaign.specialAdCategories- Special ad categories.
items[].launch.newCampaign.spendCap- Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
items[].launch.platform- The ad platform it belongs to (
meta, or a platform fromGET /platforms); fixed at creation. items[].launch.platformSettings- The platform's own launch settings (
GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta. items[].launch.publishJobId- The latest publish job.
items[].launch.publishedAt- First published.
items[].launch.scheduleAt- When publishing starts.
items[].launch.settings- 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 areplatformSettings. items[].launch.sharedWithGuests- Shared with the workspace's guests for review.
items[].launch.status- Status.One of
draft,publishing,published,failed items[].launch.updatedAt- Last change.
items[].launch.version- Increments on every change; send as
expectedVersion. items[].message- Why it conflicts.
items[].messageCode- A registered
message's stable code (such asad_exists_in_launch), for an app to say it in its language. items[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].status- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}
}
]
}'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).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
notLive- Launches not archived that are published or imported and not live.
curl "$PLUTO_API/launches/liveness" \
-H "Authorization: Bearer $PLUTO_KEY"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).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
adAccountId- act_…
adSets- Ad sets.
adSets[].externalKey- Your key.
adSets[].name- Name.
adSets[].overrides- Launch settings this ad set changes.
adSets[].targeting- Targeting (may include
metaSettings). ads- Ads.
ads[].adSet- The ad set's externalKey; absent is ungrouped.
ads[].externalKey- Your key.
ads[].mediaId- The creative: an image or a video.
ads[].name- Defaults to the launch's naming pattern.
ads[].overrides- What the ad changes.
campaignId- An existing campaign to publish into.
externalKey- Your key for the launch; applying again updates it.
name- Name.
newCampaignnewCampaign.bidStrategy- Bid strategy.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS newCampaign.budget- 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.budgetModecampaign(Advantage campaign budget) orad_set.One ofcampaign,ad_setnewCampaign.budgetPeriod- Period.One of
daily,lifetime newCampaign.budgetSharing- Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.name- Name.
newCampaign.objective- Meta objective.One of
OUTCOME_SALES,OUTCOME_TRAFFIC,OUTCOME_LEADS,OUTCOME_ENGAGEMENT,OUTCOME_AWARENESS,OUTCOME_APP_PROMOTION newCampaign.specialAdCategories- Special ad categories.
newCampaign.spendCap- Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
scheduleAt- Start.
settings- Settings over the workspace/account defaults on creation, over the current settings on update.
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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": {}
}'Validate a launch spec (dry run)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The 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
adAccountId- act_…
adSets- Ad sets.
adSets[].externalKey- Your key.
adSets[].name- Name.
adSets[].overrides- Launch settings this ad set changes.
adSets[].targeting- Targeting (may include
metaSettings). ads- Ads.
ads[].adSet- The ad set's externalKey; absent is ungrouped.
ads[].externalKey- Your key.
ads[].mediaId- The creative: an image or a video.
ads[].name- Defaults to the launch's naming pattern.
ads[].overrides- What the ad changes.
campaignId- An existing campaign to publish into.
externalKey- Your key for the launch; applying again updates it.
name- Name.
newCampaignnewCampaign.bidStrategy- Bid strategy.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS newCampaign.budget- 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.budgetModecampaign(Advantage campaign budget) orad_set.One ofcampaign,ad_setnewCampaign.budgetPeriod- Period.One of
daily,lifetime newCampaign.budgetSharing- Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.name- Name.
newCampaign.objective- Meta objective.One of
OUTCOME_SALES,OUTCOME_TRAFFIC,OUTCOME_LEADS,OUTCOME_ENGAGEMENT,OUTCOME_AWARENESS,OUTCOME_APP_PROMOTION newCampaign.specialAdCategories- Special ad categories.
newCampaign.spendCap- Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
scheduleAt- Start.
settings- Settings over the workspace/account defaults on creation, over the current settings on update.
Response
valid, every error, and the plan (created/updated per level).
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": {}
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
archived- Archived launches, a launch with several campaigns once.
assigned- The caller's ads in review or with changes requested (at most 50).
assigned[].adId- Ad.
assigned[].adName- Name.
assigned[].launchId- Launch.
assigned[].launchName- Launch name.
assigned[].mediaId- Creative.
assigned[].statusId- Review status.
changesRequested- Ads with changes requested.
inReview- Ads in review.
open- Launches not published.
published- Published launches.
curl "$PLUTO_API/launches/stats" \
-H "Authorization: Bearer $PLUTO_KEY"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
account- The ad account as synced from Meta:
id,name,currency,timezone. adSets- Ad sets in order.
adSets[].effective- The launch settings with the overrides on top.
adSets[].externalKey- Your own key.
adSets[].id- ID.
adSets[].invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
adSets[].invalid[].message- Problem.
adSets[].launchId- Launch.
adSets[].name- Name.
adSets[].overrides- Only the launch settings this ad set changes.
adSets[].platformSettings- A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's (
{}for Meta). adSets[].position- Order.
adSets[].targeting- The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
adSets[].version- Increments on every change; send as
expectedVersion. ads- Ads in order.
ads[].adSetId- Ad set; null is ungrouped.
ads[].assigneeId- Assignee.
ads[].createdAt- Created.
ads[].creativeLinkId- Shared with the ads copied from or to it in its launch group's other campaigns (
GET /ads/{id}/linked). ads[].crops- 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[].effective- The content the ad publishes: overrides, otherwise the launch's values.
ads[].externalKey- Your own key.
ads[].format- Creative format:
audiois an audio ad, where the platform has them;textis 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 ofimage,video,carousel,audio,text ads[].id- ID.
ads[].issues- Problems with the effective content.
ads[].labelIds- Labels.
ads[].launchId- Launch.
ads[].mediaId- Creative.
ads[].name- Name.
ads[].overrides- Only what this ad changes.
ads[].position- Order.
ads[].statusId- Review status.
ads[].updatedAt- Last change.
ads[].version- Increments on every change; send as
expectedVersion. campaign- The existing campaign it publishes into, as synced:
id,name,objective,status,bidStrategy,budgetMode,dailyBudget,lifetimeBudget(decimal strings or null). campaignName- The Meta campaign name ads are named with.
canDelete- Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
createPath- On a platform whose create path depends on the ad account:
smart_plus(its automated campaign type) ormanual, 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. launch- A launch: one batch of ads for a provider ad account.
launch.adAccountId- act_…
launch.archivedAt- Archived.
launch.campaignId- The existing Meta campaign it publishes into; null when it creates
newCampaign. launch.copiedFromLaunchId- The launch it was copied from to this platform.
launch.createdAt- Created.
launch.externalKey- Your own key.
launch.groupId- Its launch group (
GET /launch-groups/{id}): the launch's other campaigns are there. launch.id- ID.
launch.invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
launch.invalid[].message- Problem.
launch.label- 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.name- Name.
launch.newCampaign- The campaign it creates at publish.
launch.newCampaign.bidStrategy- Bid strategy.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS launch.newCampaign.budget- 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.budgetModecampaign(Advantage campaign budget) orad_set.One ofcampaign,ad_setlaunch.newCampaign.budgetPeriod- Period.One of
daily,lifetime launch.newCampaign.budgetSharing- Ad sets share up to 20% of their budget (ad set budgets only).
launch.newCampaign.name- Name.
launch.newCampaign.objective- Meta objective.One of
OUTCOME_SALES,OUTCOME_TRAFFIC,OUTCOME_LEADS,OUTCOME_ENGAGEMENT,OUTCOME_AWARENESS,OUTCOME_APP_PROMOTION launch.newCampaign.specialAdCategories- Special ad categories.
launch.newCampaign.spendCap- Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
launch.platform- The ad platform it belongs to (
meta, or a platform fromGET /platforms); fixed at creation. launch.platformSettings- The platform's own launch settings (
GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta. launch.publishJobId- The latest publish job.
launch.publishedAt- First published.
launch.scheduleAt- When publishing starts.
launch.settings- 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 areplatformSettings. launch.sharedWithGuests- Shared with the workspace's guests for review.
launch.status- Status.One of
draft,publishing,published,failed launch.updatedAt- Last change.
launch.version- Increments on every change; send as
expectedVersion. reviewreview.excludedreview.excluded.emptyAdSets- 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[].id- Ad set.
review.excluded.emptyAdSets[].name- Name.
review.excluded.ungroupedAdIds- Their IDs, in board order.
review.excluded.ungroupedAds- Creatives in Ungrouped. They are drafts: not published, not counted in
createsor the budget, and their gaps don't block publishing. review.items- What still blocks publishing: only ad sets with creatives and the ads in them are checked.
review.items[].action- A one-step fix:
split_ad_setrunsPOST /ad-sets/{id}/splitonadSetId. review.items[].adId- The ad it concerns.
review.items[].adName- Its name.
review.items[].adSet- The ad set it concerns, by name.
review.items[].adSetId- The ad set's ID.
review.items[].field- 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 onpath. review.items[].id- Stable item ID.
review.items[].label- Short label.
review.items[].labelCode- A registered
label's stable code (such asreview_match_campaign_objective), for an app to say it in its language; absent when the label is free text. review.items[].labelParams- The values
labelCode's sentence names, present exactly when it names any. review.items[].labelPlace- 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;labelkeeps it in English. review.items[].message- What to fix.
review.items[].nextCode- The next step's stable code when
messageis 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[].nextParams- The values
nextCode's sentence names, present exactly when it names any. review.items[].nextTopics- The policy topics the platform names beside the next step, in its own words (
TRADEMARKS, ALCOHOL), present withnextCodewhen it names any. review.items[].path- 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 inadSetId(targeting.countries,overrides.beneficiary,platformSettings.costType) or the ad inadId(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.ready- No checklist items remain.
smartPlusAccesssmartPlusAccess.learnedAt- When Pluto learned it.
smartPlusAccess.manualUntil- The last day the platform creates manual campaigns (a date).
smartPlusAccess.statusyes,noorunknown(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-Afterseconds. 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"Update a launch
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
adAccountId- act_…
campaignId- Campaign.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
label- 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. name- Name.
newCampaign- 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.bidStrategy- 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.budget- Campaign budget (budgetMode campaign) as a decimal string in the ad account's currency ("100", "99.50"). Never guessed: ask when unknown.
newCampaign.budgetMode- 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.budgetPeriod- With a campaign budget: daily, or lifetime (spent over the schedule; ad sets need an end).One of
daily,lifetime newCampaign.budgetSharing- With ad set budgets: let ad sets share up to 20% of their budget with better-performing ad sets.
newCampaign.name- Campaign name, up to 400 characters.
newCampaign.objective- 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.specialAdCategories- 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.specialAdCategoryCountry- 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.spendCap- 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.
platform- Moves a draft that never published to another platform from
GET /platforms, sent withadAccountIdthere 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. platformSettings- A launch on a platform with its own launch settings:
{campaign: {…}, adSet: {…}}, each named key replacing its value. scheduleAt- Start.
settings- 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.adNaming- Ad name pattern: {{asset.name}}, {{campaign.name}}, {{index}}, {{date}} (the ad account's day) and text.
settings.adSetNaming- Ad set name pattern, like adNaming; "" names new ad sets "Ad set N".
settings.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. settings.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
settings.catalogItems- Show products from your catalog (needs productSetId).
settings.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days settings.conversionEvent- 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.creative- Advantage+ creative enhancements per format (each is opt-in).
settings.creative.carousel- 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.image- 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.video- 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.cta- 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.customConversion- 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.delivery- 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.descriptions- Description. Keep one non-empty value.
settings.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day settings.headlines- Headline. Keep one non-empty value.
settings.instagram- Instagram account ads publish as: its Meta ID (get_meta_integration); usually the one linked to the Page. "" uses the Page.
settings.multiAdvertiser- Multi-advertiser ads: the ad can appear alongside other businesses' ads.
settings.page- 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.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
settings.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
settings.placementCrops- 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.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
settings.primaryTexts- Primary text. Publishing sends one per ad: keep one non-empty value.
settings.productSetId- Catalog product set: its numeric Meta ID.
settings.utm- 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.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day settings.websiteUrl- Website URL ads link to (https://…).
sharedWithGuests- 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
shareNewLaunchesWithGuestssays (off by default). Assigning an ad to a guest or mentioning one in a comment shares it too.
Response
adAccountId- act_…
archivedAt- Archived.
campaignId- The existing Meta campaign it publishes into; null when it creates
newCampaign. copiedFromLaunchId- The launch it was copied from to this platform.
createdAt- Created.
externalKey- Your own key.
groupId- Its launch group (
GET /launch-groups/{id}): the launch's other campaigns are there. id- ID.
invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
invalid[].message- Problem.
label- Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
name- Name.
newCampaign- The campaign it creates at publish.
newCampaign.bidStrategy- Bid strategy.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS newCampaign.budget- 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.budgetModecampaign(Advantage campaign budget) orad_set.One ofcampaign,ad_setnewCampaign.budgetPeriod- Period.One of
daily,lifetime newCampaign.budgetSharing- Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.name- Name.
newCampaign.objective- Meta objective.One of
OUTCOME_SALES,OUTCOME_TRAFFIC,OUTCOME_LEADS,OUTCOME_ENGAGEMENT,OUTCOME_AWARENESS,OUTCOME_APP_PROMOTION newCampaign.specialAdCategories- Special ad categories.
newCampaign.spendCap- Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
platform- The ad platform it belongs to (
meta, or a platform fromGET /platforms); fixed at creation. platformSettings- The platform's own launch settings (
GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta. publishJobId- The latest publish job.
publishedAt- First published.
scheduleAt- When publishing starts.
settings- 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 areplatformSettings. sharedWithGuests- Shared with the workspace's guests for review.
status- Status.One of
draft,publishing,published,failed updatedAt- Last change.
version- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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 a draft launch
Only drafts that never created anything at a provider.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500, default 200). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page, in board order.
items[].effective- The launch settings with the overrides on top.
items[].externalKey- Your own key.
items[].id- ID.
items[].invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
items[].invalid[].message- Problem.
items[].launchId- Launch.
items[].name- Name.
items[].overrides- Only the launch settings this ad set changes.
items[].platformSettings- A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's (
{}for Meta). items[].position- Order.
items[].targeting- The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
items[].version- Increments on every change; send as
expectedVersion. items[].adCount- Ads in it on the board.
nextAfter- 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-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
beforeId- Place before.
end- Delivery end, like start; "" runs without an end date.
externalKey- Your key.
name- Name.
overrides- Launch settings this ad set changes; null follows the launch again. Prefer
settings. overrides.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. overrides.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
overrides.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days overrides.conversionEvent- 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.customConversion- 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.delivery- 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.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day overrides.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
overrides.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
overrides.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
overrides.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day platformSettings- A launch on a platform with its own settings: the ad set fields of
GET /platforms/{platform}/specthis ad set changes from the launch's;nullon a key follows the launch again. settings- 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.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. settings.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
settings.bidAmount- 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.budget- 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.budgetPeriod- 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.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days settings.conversionEvent- 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.countries- Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
settings.currency- 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.customAudienceIds- Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
settings.delivery- 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.devices- Devices: mobile, desktop or both (at least one).
settings.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day settings.excludedAudienceIds- Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
settings.excludedCountries- Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
settings.excludedPlaces- 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
settings.excludedPlaces[].key- The location search's key (not for pins).
settings.excludedPlaces[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin settings.excludedPlaces[].latitude- A pin's latitude.
settings.excludedPlaces[].longitude- A pin's longitude.
settings.excludedPlaces[].name- How it reads, as the search named it; a pin's label.
settings.excludedPlaces[].radius- Distance around a city or pin, in
unit. settings.excludedPlaces[].region- The region or state a city or postal code is in.
settings.excludedPlaces[].unit- The radius's unit.One of
kilometer,mile settings.gender- Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of
All,Women,Men settings.interestIds- Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
settings.localeIds- Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
settings.maxAge- Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
settings.minAge- 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.optimization- Performance goal (Meta's optimization goal).
inherituses 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 ofinherit,REACH,IMPRESSIONS,AD_RECALL_LIFT,THRUPLAY,LANDING_PAGE_VIEWS,LINK_CLICKS,OFFSITE_CONVERSIONS,APP_INSTALLS,VALUE settings.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
settings.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
settings.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
settings.places- 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
countriesoverlaps 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
settings.places[].key- The location search's key (not for pins).
settings.places[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin settings.places[].latitude- A pin's latitude.
settings.places[].longitude- A pin's longitude.
settings.places[].name- How it reads, as the search named it; a pin's label.
settings.places[].radius- Distance around a city or pin, in
unit. settings.places[].region- The region or state a city or postal code is in.
settings.places[].unit- The radius's unit.One of
kilometer,mile settings.roasGoal- Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
settings.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day start- Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.
targeting- The ad set's stored targeting, merged key by key (null removes a key). Prefer
settings, which takes the same values flat. targeting.bidAmount- 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.budget- 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.budgetPeriod- 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.countries- Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
targeting.excludedCountries- Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
targeting.excludedPlaces- 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
targeting.excludedPlaces[].key- The location search's key (not for pins).
targeting.excludedPlaces[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin targeting.excludedPlaces[].latitude- A pin's latitude.
targeting.excludedPlaces[].longitude- A pin's longitude.
targeting.excludedPlaces[].name- How it reads, as the search named it; a pin's label.
targeting.excludedPlaces[].radius- Distance around a city or pin, in
unit. targeting.excludedPlaces[].region- The region or state a city or postal code is in.
targeting.excludedPlaces[].unit- The radius's unit.One of
kilometer,mile targeting.gender- Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of
All,Women,Men targeting.maxAge- Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
targeting.metaSettings- Launch settings this ad set changes; null follows the launch again. Prefer
settings. targeting.metaSettings.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. targeting.metaSettings.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
targeting.metaSettings.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days targeting.metaSettings.conversionEvent- 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.customConversion- 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.delivery- 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.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day targeting.metaSettings.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
targeting.metaSettings.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
targeting.metaSettings.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
targeting.metaSettings.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day targeting.minAge- 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.places- 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
countriesoverlaps 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
targeting.places[].key- The location search's key (not for pins).
targeting.places[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin targeting.places[].latitude- A pin's latitude.
targeting.places[].longitude- A pin's longitude.
targeting.places[].name- How it reads, as the search named it; a pin's label.
targeting.places[].radius- Distance around a city or pin, in
unit. targeting.places[].region- The region or state a city or postal code is in.
targeting.places[].unit- The radius's unit.One of
kilometer,mile targeting.roasGoal- Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
targeting.setup- Setup: performance goal, audiences, devices and delivery times.
targeting.setup.customAudienceIds- Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
targeting.setup.devices- Devices: mobile, desktop or both (at least one).
targeting.setup.end- Delivery end, like start; "" runs without an end date. A lifetime budget needs one.
targeting.setup.excludedAudienceIds- Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
targeting.setup.interestIds- Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
targeting.setup.localeIds- Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
targeting.setup.optimization- Performance goal (Meta's optimization goal).
inherituses 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 ofinherit,REACH,IMPRESSIONS,AD_RECALL_LIFT,THRUPLAY,LANDING_PAGE_VIEWS,LINK_CLICKS,OFFSITE_CONVERSIONS,APP_INSTALLS,VALUE targeting.setup.start- Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.
templateId- Start from this ad set template.
Response
effective- The launch settings with the overrides on top.
externalKey- Your own key.
id- ID.
invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
invalid[].message- Problem.
launchId- Launch.
name- Name.
overrides- Only the launch settings this ad set changes.
platformSettings- A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's (
{}for Meta). position- Order.
targeting- The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
version- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
items- Ad sets.
items[].beforeId- Place before.
items[].commandId- This item's command ID.
items[].end- Delivery end, like start; "" runs without an end date.
items[].externalKey- Your key.
items[].name- Name.
items[].overrides- Launch settings this ad set changes; null follows the launch again. Prefer
settings. items[].overrides.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. items[].overrides.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].overrides.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days items[].overrides.conversionEvent- 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.customConversion- 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.delivery- 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.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day items[].overrides.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].overrides.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].overrides.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
items[].overrides.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day items[].settings- 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.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. items[].settings.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].settings.bidAmount- 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.budget- 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.budgetPeriod- 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.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days items[].settings.conversionEvent- 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.countries- Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
items[].settings.currency- 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.customAudienceIds- Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
items[].settings.delivery- 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.devices- Devices: mobile, desktop or both (at least one).
items[].settings.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day items[].settings.excludedAudienceIds- Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
items[].settings.excludedCountries- Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
items[].settings.excludedPlaces- 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
items[].settings.excludedPlaces[].key- The location search's key (not for pins).
items[].settings.excludedPlaces[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin items[].settings.excludedPlaces[].latitude- A pin's latitude.
items[].settings.excludedPlaces[].longitude- A pin's longitude.
items[].settings.excludedPlaces[].name- How it reads, as the search named it; a pin's label.
items[].settings.excludedPlaces[].radius- Distance around a city or pin, in
unit. items[].settings.excludedPlaces[].region- The region or state a city or postal code is in.
items[].settings.excludedPlaces[].unit- The radius's unit.One of
kilometer,mile items[].settings.gender- Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of
All,Women,Men items[].settings.interestIds- Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
items[].settings.localeIds- Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
items[].settings.maxAge- Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
items[].settings.minAge- 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.optimization- Performance goal (Meta's optimization goal).
inherituses 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 ofinherit,REACH,IMPRESSIONS,AD_RECALL_LIFT,THRUPLAY,LANDING_PAGE_VIEWS,LINK_CLICKS,OFFSITE_CONVERSIONS,APP_INSTALLS,VALUE items[].settings.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].settings.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].settings.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
items[].settings.places- 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
countriesoverlaps 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
items[].settings.places[].key- The location search's key (not for pins).
items[].settings.places[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin items[].settings.places[].latitude- A pin's latitude.
items[].settings.places[].longitude- A pin's longitude.
items[].settings.places[].name- How it reads, as the search named it; a pin's label.
items[].settings.places[].radius- Distance around a city or pin, in
unit. items[].settings.places[].region- The region or state a city or postal code is in.
items[].settings.places[].unit- The radius's unit.One of
kilometer,mile items[].settings.roasGoal- Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
items[].settings.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day items[].start- Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.
items[].targeting- The ad set's stored targeting, merged key by key (null removes a key). Prefer
settings, which takes the same values flat. items[].targeting.bidAmount- 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.budget- 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.budgetPeriod- 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.countries- Countries and territories to reach, as ISO 3166-1 alpha-2 codes (US, CA, GB, DK). Never guessed: ask when unknown.
items[].targeting.excludedCountries- Countries to leave out, ISO 3166-1 alpha-2. A country can't be both included and excluded.
items[].targeting.excludedPlaces- 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
items[].targeting.excludedPlaces[].key- The location search's key (not for pins).
items[].targeting.excludedPlaces[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin items[].targeting.excludedPlaces[].latitude- A pin's latitude.
items[].targeting.excludedPlaces[].longitude- A pin's longitude.
items[].targeting.excludedPlaces[].name- How it reads, as the search named it; a pin's label.
items[].targeting.excludedPlaces[].radius- Distance around a city or pin, in
unit. items[].targeting.excludedPlaces[].region- The region or state a city or postal code is in.
items[].targeting.excludedPlaces[].unit- The radius's unit.One of
kilometer,mile items[].targeting.gender- Who to reach: All, Women or Men. With Advantage+ audience it's a suggestion.One of
All,Women,Men items[].targeting.maxAge- Maximum age, 13 to 65 (65 means 65+). With Advantage+ audience it's a suggestion.
items[].targeting.metaSettings- Launch settings this ad set changes; null follows the launch again. Prefer
settings. items[].targeting.metaSettings.advantagePlacements- true: Advantage+ placements (Meta places ads everywhere eligible). false: manual placements, only
placementsandplacementPositions. items[].targeting.metaSettings.audience- 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.beneficiary- EU advertiser: who the ads benefit (required by Meta when reaching the EU).
items[].targeting.metaSettings.clickAttribution- Click-through attribution window: "1 day" or "7 days".One of
1 day,7 days items[].targeting.metaSettings.conversionEvent- 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.customConversion- 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.delivery- 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.engagedAttribution- Engaged-view attribution window (eligible video ads): "Off" or "1 day".One of
Off,1 day items[].targeting.metaSettings.payer- EU advertiser: who pays for the ads (required by Meta when reaching the EU).
items[].targeting.metaSettings.pixel- The pixel (dataset) that tracks conversions: its numeric Meta ID (get_meta_integration). "" follows the launch's pixel.
items[].targeting.metaSettings.placementPositions- 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.placements- Manual placements: the platforms to show on (with advantagePlacements false).
items[].targeting.metaSettings.viewAttribution- View-through attribution window: "Off" or "1 day".One of
Off,1 day items[].targeting.minAge- 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.places- 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
countriesoverlaps 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[].address- 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[].country- Its ISO 3166-1 alpha-2 country, as the search answered.
items[].targeting.places[].key- The location search's key (not for pins).
items[].targeting.places[].kind- region, city, postalCode, market (a DMA) or pin.One of
region,city,postalCode,market,pin items[].targeting.places[].latitude- A pin's latitude.
items[].targeting.places[].longitude- A pin's longitude.
items[].targeting.places[].name- How it reads, as the search named it; a pin's label.
items[].targeting.places[].radius- Distance around a city or pin, in
unit. items[].targeting.places[].region- The region or state a city or postal code is in.
items[].targeting.places[].unit- The radius's unit.One of
kilometer,mile items[].targeting.roasGoal- Minimum return on ad spend for bid strategy LOWEST_COST_WITH_MIN_ROAS, like "2.5" (2.5x).
items[].targeting.setup- Setup: performance goal, audiences, devices and delivery times.
items[].targeting.setup.customAudienceIds- Custom audiences to include: numeric Meta IDs separated by commas (list_audiences). "" clears.
items[].targeting.setup.devices- Devices: mobile, desktop or both (at least one).
items[].targeting.setup.end- Delivery end, like start; "" runs without an end date. A lifetime budget needs one.
items[].targeting.setup.excludedAudienceIds- Custom audiences to exclude: numeric Meta IDs separated by commas. "" clears.
items[].targeting.setup.interestIds- Detailed targeting interests: numeric Meta IDs separated by commas (search_targeting). "" clears.
items[].targeting.setup.localeIds- Languages: numeric Meta locale keys separated by commas (search_platform_targeting, facet languages). "" clears.
items[].targeting.setup.optimization- Performance goal (Meta's optimization goal).
inherituses 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 ofinherit,REACH,IMPRESSIONS,AD_RECALL_LIFT,THRUPLAY,LANDING_PAGE_VIEWS,LINK_CLICKS,OFFSITE_CONVERSIONS,APP_INSTALLS,VALUE items[].targeting.setup.start- Delivery start: RFC 3339, or YYYY-MM-DDTHH:MM in the ad account's time zone; "" starts when published.
Response
items- One outcome per item, in order:
adSetwhen accepted;errorswhen rejected (acommandIdreused for other input is rejected oncommandId);messageon a conflict. items[].adSet- An ad set. Stores explicit overrides only; empty means inherit from the launch.
items[].adSet.effective- The launch settings with the overrides on top.
items[].adSet.externalKey- Your own key.
items[].adSet.id- ID.
items[].adSet.invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
items[].adSet.invalid[].message- Problem.
items[].adSet.launchId- Launch.
items[].adSet.name- Name.
items[].adSet.overrides- Only the launch settings this ad set changes.
items[].adSet.platformSettings- 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.position- Order.
items[].adSet.targeting- The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
items[].adSet.version- Increments on every change; send as
expectedVersion. items[].commandId- The item's command ID.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].message- Why it conflicts.
items[].messageCode- A registered
message's stable code (such asad_exists_in_launch), for an app to say it in its language. items[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].status- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}
}
}
]
}'Create ads in bulk
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
items- Ads.
items[].adSetId- Ad set.
items[].commandId- This item's command ID.
items[].edit- An edit in effective values. Values equal to the launch's follow the launch. URL parameters are the launch's
utmsetting unless a Meta ad sets its own. items[].edit.bestCardsFirst- A carousel shows its best-performing cards first (default true). Meta only.
items[].edit.cards- 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[].description- The card's description, where the platform shows one.
items[].edit.cards[].headline- The card's headline.
items[].edit.cards[].mediaId- The card's image or video: a media library ID. The first card's is the ad's media.
items[].edit.cards[].url- The page the card opens (https://…).
items[].edit.creative- Creative settings.
items[].edit.creative.catalogItems- Show products from your catalog.
items[].edit.creative.features- Advantage+ creative enhancements per format (each is opt-in).
items[].edit.creative.multiAdvertiser- Multi-advertiser ads.
items[].edit.creative.placementCrops- 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.productSetId- Catalog product set: its numeric Meta ID.
items[].edit.cta- 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.description- Description.
items[].edit.displayLink- Meta: the link the ad shows instead of its website's domain (Ads Manager's Display link); "" removes it.
items[].edit.endCard- A carousel ends with a card showing the Page (default true). Meta only.
items[].edit.headline- Headline.
items[].edit.identity- The Page and Instagram account the ad publishes as.
items[].edit.identity.instagram- Instagram account: its Meta ID; usually the one linked to the Page.
items[].edit.identity.page- Facebook Page: its numeric Meta ID (get_meta_integration).
items[].edit.imageCrops- 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:1items[].edit.imageCrops.1:1items[].edit.imageCrops.4:5items[].edit.imageCrops.9:16items[].edit.placementMedia- 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.feedsitems[].edit.placementMedia.rightColumnitems[].edit.placementMedia.storiesitems[].edit.text- Primary text.
items[].edit.url- Website URL the ad links to (https://…).
items[].edit.useLaunch- 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.utm- Meta: the ad's own URL parameters (Ads Manager's per-ad URL parameters, like utm_content={{ad.name}}); the launch's
utmvalue follows the launch again, "" sends none. items[].externalKey- Your key.
items[].mediaId- The creative: an image or a video from the library. Media still processing is fine; publishing waits for it.
items[].name- Name.
items[].overrides- Stored overrides; values equal to the launch's collapse to inherit. Prefer
edit. items[].overrides.bestCardsFirstfalsewhen a carousel keeps its card order (default true). Meta only.items[].overrides.cards- A carousel ad's cards, in order.
items[].overrides.cards[].description- The card's description, where the platform shows one.
items[].overrides.cards[].headline- The card's headline.
items[].overrides.cards[].mediaId- The card's image or video: a media library ID. The first card's is the ad's media.
items[].overrides.cards[].url- The page the card opens (https://…).
items[].overrides.copyVariations- Copy lists this ad changes; a list left out follows the launch.
items[].overrides.copyVariations.descriptions- Description; publishing sends one.
items[].overrides.copyVariations.headlines- Headline; publishing sends one.
items[].overrides.copyVariations.primaryTexts- Primary text; publishing sends one.
items[].overrides.creativeSettings- Creative settings this ad changes.
items[].overrides.creativeSettings.catalogItems- Catalog items.
items[].overrides.creativeSettings.creative- Advantage+ creative enhancements per format (each is opt-in).
items[].overrides.creativeSettings.multiAdvertiser- Multi-advertiser ads.
items[].overrides.creativeSettings.placementCrops- 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.productSetId- Product set ID.
items[].overrides.cta- 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.endCardfalsewhen a carousel has no end card (default true). Meta only.items[].overrides.identity- Page and Instagram account IDs; null follows the launch.
items[].overrides.identity.instagramitems[].overrides.identity.pageitems[].overrides.imageCrops- 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:1items[].overrides.imageCrops.1:1items[].overrides.imageCrops.4:5items[].overrides.imageCrops.9:16items[].overrides.placementMedia- 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.feedsitems[].overrides.placementMedia.rightColumnitems[].overrides.placementMedia.storiesitems[].overrides.url- Website URL.
items[].statusId- Review status.
Response
items- One outcome per item, in order:
adwhen accepted;errorswhen rejected (acommandIdreused for other input is rejected oncommandId);messageon a conflict. items[].ad- An ad. Stores explicit overrides only; effective values resolve at read time.
items[].ad.adSetId- Ad set; null is ungrouped.
items[].ad.assigneeId- Assignee.
items[].ad.createdAt- Created.
items[].ad.creativeLinkId- Shared with the ads copied from or to it in its launch group's other campaigns (
GET /ads/{id}/linked). items[].ad.crops- 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.effective- The content the ad publishes: overrides, otherwise the launch's values.
items[].ad.externalKey- Your own key.
items[].ad.format- Creative format:
audiois an audio ad, where the platform has them;textis 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 ofimage,video,carousel,audio,text items[].ad.id- ID.
items[].ad.issues- Problems with the effective content.
items[].ad.labelIds- Labels.
items[].ad.launchId- Launch.
items[].ad.mediaId- Creative.
items[].ad.name- Name.
items[].ad.overrides- Only what this ad changes.
items[].ad.position- Order.
items[].ad.statusId- Review status.
items[].ad.updatedAt- Last change.
items[].ad.version- Increments on every change; send as
expectedVersion. items[].commandId- The item's command ID.
items[].errors- Every problem with this item.
items[].errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. items[].errors[].field- JSON-pointer-like path.
items[].errors[].message- Problem.
items[].errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. items[].message- Why it conflicts.
items[].messageCode- A registered
message's stable code (such asad_exists_in_launch), for an app to say it in its language. items[].messageParams- The values
messageCode's sentence names, present exactly when it is. items[].status- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}
]
}'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}.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
adad.edit- An edit in effective values. Values equal to the launch's follow the launch. URL parameters are the launch's
utmsetting unless a Meta ad sets its own. ad.edit.bestCardsFirst- A carousel shows its best-performing cards first (default true). Meta only.
ad.edit.cards- 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[].description- The card's description, where the platform shows one.
ad.edit.cards[].headline- The card's headline.
ad.edit.cards[].mediaId- The card's image or video: a media library ID. The first card's is the ad's media.
ad.edit.cards[].url- The page the card opens (https://…).
ad.edit.creative- Creative settings.
ad.edit.creative.catalogItems- Show products from your catalog.
ad.edit.creative.features- Advantage+ creative enhancements per format (each is opt-in).
ad.edit.creative.multiAdvertiser- Multi-advertiser ads.
ad.edit.creative.placementCrops- 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.productSetId- Catalog product set: its numeric Meta ID.
ad.edit.cta- 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.description- Description.
ad.edit.displayLink- Meta: the link the ad shows instead of its website's domain (Ads Manager's Display link); "" removes it.
ad.edit.endCard- A carousel ends with a card showing the Page (default true). Meta only.
ad.edit.headline- Headline.
ad.edit.identity- The Page and Instagram account the ad publishes as.
ad.edit.identity.instagram- Instagram account: its Meta ID; usually the one linked to the Page.
ad.edit.identity.page- Facebook Page: its numeric Meta ID (get_meta_integration).
ad.edit.imageCrops- 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:1ad.edit.imageCrops.1:1ad.edit.imageCrops.4:5ad.edit.imageCrops.9:16ad.edit.placementMedia- 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.feedsad.edit.placementMedia.rightColumnad.edit.placementMedia.storiesad.edit.text- Primary text.
ad.edit.url- Website URL the ad links to (https://…).
ad.edit.useLaunch- 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.utm- Meta: the ad's own URL parameters (Ads Manager's per-ad URL parameters, like utm_content={{ad.name}}); the launch's
utmvalue follows the launch again, "" sends none. ad.overrides- Stored overrides; values equal to the launch's collapse to inherit. Prefer
edit. ad.overrides.bestCardsFirstfalsewhen a carousel keeps its card order (default true). Meta only.ad.overrides.cards- A carousel ad's cards, in order.
ad.overrides.cards[].description- The card's description, where the platform shows one.
ad.overrides.cards[].headline- The card's headline.
ad.overrides.cards[].mediaId- The card's image or video: a media library ID. The first card's is the ad's media.
ad.overrides.cards[].url- The page the card opens (https://…).
ad.overrides.copyVariations- Copy lists this ad changes; a list left out follows the launch.
ad.overrides.copyVariations.descriptions- Description; publishing sends one.
ad.overrides.copyVariations.headlines- Headline; publishing sends one.
ad.overrides.copyVariations.primaryTexts- Primary text; publishing sends one.
ad.overrides.creativeSettings- Creative settings this ad changes.
ad.overrides.creativeSettings.catalogItems- Catalog items.
ad.overrides.creativeSettings.creative- Advantage+ creative enhancements per format (each is opt-in).
ad.overrides.creativeSettings.multiAdvertiser- Multi-advertiser ads.
ad.overrides.creativeSettings.placementCrops- 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.productSetId- Product set ID.
ad.overrides.cta- 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.endCardfalsewhen a carousel has no end card (default true). Meta only.ad.overrides.identity- Page and Instagram account IDs; null follows the launch.
ad.overrides.identity.instagramad.overrides.identity.pagead.overrides.imageCrops- 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:1ad.overrides.imageCrops.1:1ad.overrides.imageCrops.4:5ad.overrides.imageCrops.9:16ad.overrides.placementMedia- 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.feedsad.overrides.placementMedia.rightColumnad.overrides.placementMedia.storiesad.overrides.url- Website URL.
ad.statusId- Review status.
adSetId- The ad set the ads go in; a new one when absent.
adSetName- Without
adSetId: the new ad set's name. adSetSettings- Without
adSetId: the new ad set's settings, asPOST /launches/{id}/ad-setstakes them. folderId- Every usable file of this folder.
includeUsed- Also make ads of files the launch already has ads of.
kind- Folder only:
image,videoordocument. mediaIds- These files, in this order (instead of
folderId); 1 to 5,000. order- Folder only:
name(default),oldestornewest.
Response
adSetCreated- The ad set was made by this request.
adSetId- The ad set every ad goes in.
adSets- Ad sets the ads end up in: 1, the one they go in. Kept for older clients; nothing is split now.
ads- Ads the job makes.
jobId- The job making the ads.
launchId- The launch.
skippedskipped.alreadyInLaunch- Files the launch already uses.
skipped.notUsable- Failed or archived files.
splitSuggested- On Meta, when the ad set will hold more than Meta's usual 50 ads: the split
POST /ad-sets/{id}/splitmakes if wanted. Absent otherwise. splitSuggested[].adSetId- The ad set.
splitSuggested[].ads- The ads it will hold.
splitSuggested[].parts- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'Archive or restore a launch
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
archived- false restores.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
Response
adAccountId- act_…
archivedAt- Archived.
campaignId- The existing Meta campaign it publishes into; null when it creates
newCampaign. copiedFromLaunchId- The launch it was copied from to this platform.
createdAt- Created.
externalKey- Your own key.
groupId- Its launch group (
GET /launch-groups/{id}): the launch's other campaigns are there. id- ID.
invalid- 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[].field- JSON-pointer-like path, as a refusal names it.
invalid[].message- Problem.
label- Its own name in its launch group when a person gave one; null goes by a default (the launch group lists every campaign's).
name- Name.
newCampaign- The campaign it creates at publish.
newCampaign.bidStrategy- Bid strategy.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS newCampaign.budget- 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.budgetModecampaign(Advantage campaign budget) orad_set.One ofcampaign,ad_setnewCampaign.budgetPeriod- Period.One of
daily,lifetime newCampaign.budgetSharing- Ad sets share up to 20% of their budget (ad set budgets only).
newCampaign.name- Name.
newCampaign.objective- Meta objective.One of
OUTCOME_SALES,OUTCOME_TRAFFIC,OUTCOME_LEADS,OUTCOME_ENGAGEMENT,OUTCOME_AWARENESS,OUTCOME_APP_PROMOTION newCampaign.specialAdCategories- Special ad categories.
newCampaign.spendCap- Campaign spending limit (Ads Manager's) in the ad account currency: the most the campaign spends over its life. Absent for none.
platform- The ad platform it belongs to (
meta, or a platform fromGET /platforms); fixed at creation. platformSettings- The platform's own launch settings (
GET /platforms/{platform}/spec): its campaign and what its ad sets inherit. Null for Meta. publishJobId- The latest publish job.
publishedAt- First published.
scheduleAt- When publishing starts.
settings- 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 areplatformSettings. sharedWithGuests- Shared with the workspace's guests for review.
status- Status.One of
draft,publishing,published,failed updatedAt- Last change.
version- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adSets- Every archived ad set, most recent first.
adSets[].archivedAt- Archived.
adSets[].archivedByadSets[].archivedBy.id- Person, API key or agent client.
adSets[].archivedBy.kind- Actor kind.One of
person,api_key,agent,system adSets[].deletedAtMeta- Deleted at its ad platform: restoring creates a new draft copy.
adSets[].id- ID.
adSets[].name- Name.
adSets[].version- Version.
ads- A page of archived ads, most recent first.
ads[].adSetIdads[].archivedAt- Archived.
ads[].archivedByads[].archivedBy.id- Person, API key or agent client.
ads[].archivedBy.kind- Actor kind.One of
person,api_key,agent,system ads[].commentCount- Comments (not deleted); still readable.
ads[].deletedAtMeta- Deleted at its ad platform: restoring creates a new draft copy.
ads[].id- ID.
ads[].mediaIdads[].name- Name.
ads[].version- Version.
launchId- Launch.
nextAfter- 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-Afterseconds. 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"Change the launch's campaign budget
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
amount- In the ad account currency.
Response
availableAt- When it runs: now, or on Meta when its limit of 4 budget changes per ad set per hour allows.
jobId- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
deepCopy- Ad sets and campaigns: copy what is inside too (default false).
endTime- Ad sets and campaigns: when the copied ad sets end.
intoAdSetId- Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignId- Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsrenameOptions.prefix- Put before the name.
renameOptions.strategy- Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of
ONLY_TOP_LEVEL_RENAME,DEEP_RENAME,NO_RENAME renameOptions.suffix- Put after the name (Meta's default is a localized " - Copy").
startTime- Ad sets and campaigns: when the copied ad sets start.
statusOption- How the copy starts (default PAUSED).One of
PAUSED,ACTIVE,INHERITED_FROM_SOURCE
Response
jobId- The copy job; its items name each copy (
output.copiedId). level- What is copied.One of
campaign,ad_set,ad objects- How many objects the job copies.
sourceId- The original's ID on its platform.
statusOption- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
end- The last day it runs (
YYYY-MM-DD);nulllets it run on. start- The first day it runs (
YYYY-MM-DD); only for a campaign that hasn't started.
Response
availableAt- When it runs.
jobId- 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;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
expectedVersion- The launch's version last read.
Response
deletes- What the job removes at the platform.
deletes[].entitydeletes[].iddeletes[].providerIdjobId- 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;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
amount- The budget's new amount, in the ad account's currency.
campaignIds- Every campaign on the budget, as the
409ofPATCH /launches/{id}/campaign/budgetlisted them.
Response
availableAt- When it runs.
campaigns- Every campaign the change reaches.
campaigns[].id- The platform's ID.
campaigns[].name- Its name at the platform.
jobId- The job applying the change; follow it with GET /jobs/{id}.
sharedBudget- The budget that changes.
sharedBudget.id- The platform's ID.
sharedBudget.name- 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
sharedBudgetandcampaigns), the campaign has a budget of its own, or the launch isn't live. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
]
}'Pause or activate the launch's campaign
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
status- Delivery.One of
ACTIVE,PAUSED
Response
availableAt- When it runs: now, or on Meta when its limit of 4 budget changes per ad set per hour allows.
jobId- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
impressionShare- An impression share target: where on the results page, how much, and at what limit.
impressionShare.location- Where on the results page the ads should show.One of
ANYWHERE_ON_PAGE,TOP_OF_PAGE,ABSOLUTE_TOP_OF_PAGE impressionShare.maxCpc- The most a click may cost, a decimal in the ad account's currency.
impressionShare.percent- Percent of impressions to aim for, 1 to 100.
maxCpc- The most a click may cost, a decimal in the ad account's currency;
""clears it. targetCpa- The cost per action to aim for, a decimal in the ad account's currency;
""clears it. targetRoas- The return on ad spend to aim for, in percent (
"350"is 350%);""clears it.
Response
availableAt- When it runs.
jobId- 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;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
adAccountId- The ad account on that platform.
dryRun- Answer the plan without copying.
name- Name; defaults to "<name> copy" (on another platform, the name the launch group's naming rule gives it).
platform- Copy to this platform as another campaign of the launch (default: the launch's own, a new launch).
Response
code- Stable code.One of
bad_request,unauthenticated,forbidden,not_found,conflict,invalid,rate_limited,unavailable,internal current- The current entity, on a stale
expectedVersion(409). errors- Every field problem (422).
errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. errors[].field- JSON-pointer-like path.
errors[].message- Problem.
errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. requestId- The request's ID, as in the
x-request-idheader. Include it when you report a problem. status- HTTP status.
title- What went wrong, for the person or agent reading it.
titleCode- A registered
title's stable code (such asnot_found_the_launch), for an app to say the title in its language; absent for a title without one.titlereads the same either way. titleParams- The values
titleCode's sentence names, present exactly whentitleCodeis. traceId- The request's trace ID, as in the
x-trace-idheader. type- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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 what's published
Published objects and their status.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
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-Afterseconds. 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"Preview a publish
What a publish would do, and what blocks it.
Returns what an approval must echo: launchVersion, adAccountId and budgetSummary.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- act_…
budgetChanges- Live ad sets whose budget changes, e.g. after a split divided it.
budgetChanges[].adSetId- A live ad set.
budgetChanges[].live- The budget running at Meta now (decimal).
budgetChanges[].pending- The budget after publishing (decimal).
budgetChanges[].perioddailyorlifetime.budgetSummary- Echo exactly in the approval; null until ready.
budgetSummary.adSets- Ad set budgets.
budgetSummary.adSets[].adSetId- Ad set.
budgetSummary.adSets[].amount- In the ad account currency.
budgetSummary.adSets[].period- Period.One of
daily,lifetime budgetSummary.campaign- The new campaign's budget (Advantage campaign budget); null with ad set budgets or an existing campaign.
budgetSummary.campaign.amount- In the ad account currency.
budgetSummary.campaign.period- Period.One of
daily,lifetime budgetSummary.currency- ISO 4217 currency of every amount.
budgetSummary.dailyTotal- Sum of daily budgets; null when there are none.
budgetSummary.lifetimeTotal- Sum of lifetime budgets; null when there are none.
createPath- On a platform whose create path depends on the ad account:
smart_plus(its automated campaign type) ormanual. 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. createscreates.adSets- Ad sets.
creates.ads- Ads.
creates.campaigns- Campaigns.
creates.media- Media uploads.
currency- ISO 4217 of the ad account.
excludedexcluded.emptyAdSets- Ad sets without creatives. Meta delivers only through ads, so they aren't created (nor their budget approved) until they have one.
excluded.emptyAdSets[].id- Ad set.
excluded.emptyAdSets[].name- Name.
excluded.ungroupedAdIds- Their IDs, in board order.
excluded.ungroupedAds- Creatives in Ungrouped. They are drafts: not published, not counted in
createsor the budget, and their gaps don't block publishing. items- The checklist plus publishing's own checks.
items[].action- A one-step fix:
split_ad_setrunsPOST /ad-sets/{id}/splitonadSetId. items[].adId- The ad it concerns.
items[].adName- Its name.
items[].adSet- The ad set it concerns, by name.
items[].adSetId- The ad set's ID.
items[].field- 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 onpath. items[].id- Stable item ID.
items[].label- Short label.
items[].labelCode- A registered
label's stable code (such asreview_match_campaign_objective), for an app to say it in its language; absent when the label is free text. items[].labelParams- The values
labelCode's sentence names, present exactly when it names any. items[].labelPlace- 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;labelkeeps it in English. items[].message- What to fix.
items[].nextCode- The next step's stable code when
messageis a registered next step (a platform's own check), for an app to say it under the label in its language; absent otherwise. items[].nextParams- The values
nextCode's sentence names, present exactly when it names any. items[].nextTopics- The policy topics the platform names beside the next step, in its own words (
TRADEMARKS, ALCOHOL), present withnextCodewhen it names any. items[].path- 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 inadSetId(targeting.countries,overrides.beneficiary,platformSettings.costType) or the ad inadId(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. launchId- Launch.
launchVersion- Approve this exact version.
ready- Nothing is in the way.
scheduleAt- Scheduled start.
smartPlusAccesssmartPlusAccess.learnedAt- When Pluto learned it.
smartPlusAccess.manualUntil- The last day the platform creates manual campaigns (a date).
smartPlusAccess.statusyes,noorunknown(not tried yet).status- Launch status.
timezone- 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-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
approvalapproval.adAccountId- The ad account, as the preview gave it.
approval.budgetSummaryapproval.budgetSummary.adSets- Ad set budgets.
approval.budgetSummary.adSets[].adSetId- Ad set.
approval.budgetSummary.adSets[].amount- In the ad account currency.
approval.budgetSummary.adSets[].period- Period.One of
daily,lifetime approval.budgetSummary.campaign- The new campaign's budget (Advantage campaign budget); null with ad set budgets or an existing campaign.
approval.budgetSummary.campaign.amount- In the ad account currency.
approval.budgetSummary.campaign.period- Period.One of
daily,lifetime approval.budgetSummary.currency- ISO 4217 currency of every amount.
approval.budgetSummary.dailyTotal- Sum of daily budgets; null when there are none.
approval.budgetSummary.lifetimeTotal- Sum of lifetime budgets; null when there are none.
approval.launchVersion- Version.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
Response
jobId- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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
}'Stop a publish that hasn't finished
Objects already created on the platform stay live.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"Read a launch back from its ad platform
Read published objects back from the launch's ad platform now.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
jobId- 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-Afterseconds. 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 the readiness checklist
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
excludedexcluded.emptyAdSets- Ad sets without creatives. Meta delivers only through ads, so they aren't created (nor their budget approved) until they have one.
excluded.emptyAdSets[].id- Ad set.
excluded.emptyAdSets[].name- Name.
excluded.ungroupedAdIds- Their IDs, in board order.
excluded.ungroupedAds- Creatives in Ungrouped. They are drafts: not published, not counted in
createsor the budget, and their gaps don't block publishing. items- What still blocks publishing: only ad sets with creatives and the ads in them are checked.
items[].action- A one-step fix:
split_ad_setrunsPOST /ad-sets/{id}/splitonadSetId. items[].adId- The ad it concerns.
items[].adName- Its name.
items[].adSet- The ad set it concerns, by name.
items[].adSetId- The ad set's ID.
items[].field- 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 onpath. items[].id- Stable item ID.
items[].label- Short label.
items[].labelCode- A registered
label's stable code (such asreview_match_campaign_objective), for an app to say it in its language; absent when the label is free text. items[].labelParams- The values
labelCode's sentence names, present exactly when it names any. items[].labelPlace- 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;labelkeeps it in English. items[].message- What to fix.
items[].nextCode- The next step's stable code when
messageis a registered next step (a platform's own check), for an app to say it under the label in its language; absent otherwise. items[].nextParams- The values
nextCode's sentence names, present exactly when it names any. items[].nextTopics- The policy topics the platform names beside the next step, in its own words (
TRADEMARKS, ALCOHOL), present withnextCodewhen it names any. items[].path- 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 inadSetId(targeting.countries,overrides.beneficiary,platformSettings.costType) or the ad inadId(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. ready- 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-Afterseconds. 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"List pending changes
Pending changes to published objects.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
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-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
changes- Only these changes; the rest stay pending. A change edited since it was read is a 409 naming it in
stale, with the currentrevisionsVersion. changes[].field- Optional: one field of it; omit for every change of the object.
changes[].id- The object: the launch ID for its campaign, an ad set or an ad.
changes[].version- The change's
versionwithfield, the object'sversionwithout. revisionsVersion- From GET /launches/{id}/revisions: every pending change. Omit when sending
changes.
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The launch's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
changes- Only these changes; the rest stay pending. A change edited since it was read is a 409 naming it in
stale, with the currentrevisionsVersion. changes[].field- Optional: one field of it; omit for every change of the object.
changes[].id- The object: the launch ID for its campaign, an ad set or an ad.
changes[].version- The change's
versionwithfield, the object'sversionwithout. revisionsVersion- From GET /launches/{id}/revisions: every pending change. Omit when sending
changes.
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
}'