Ad sets
Edit, split and duplicate a launch's ad sets, and change live ones.
Apply a previewed bulk edit of ad sets
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
operations- Operations.
snapshotToken- From the preview.
Response
Applied count, conflicts and the changeset ID. Applied in chunks by the job jobId; pending counts items a worker was still applying when the request stopped waiting.
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/ad-sets/bulk/apply" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: ba6445b0-049e-4cac-9778-b7200db1c8ab" \
-H "Content-Type: application/json" \
-d '{
"operations": [
{}
],
"snapshotToken": "sMZ0Wxx5xHApvF4aQCnr8ubVHAjBDCQirVXxIFYm"
}'Preview a bulk edit of ad sets
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
operations- Operations.
selector- Filters or explicit
ids.
Response
affected- Items the selector matched (the snapshot).
approvalResets- Approved ads whose reviewed content changes, so they return to review.
changed- Items the operations change.
entity- What the edit changes.One of
ad,ad_set expiresAt- The snapshot token expires then.
problems- Every item that would be rejected, with the reason.
problems[].id- Item.
problems[].message- Why it can't be changed.
published- Items already created at a provider: their change becomes a pending revision to publish.
rejected- Items the operations can't apply to (see
problems). samples- Before/after of the first changed items.
samples[].after- Changed fields after.
samples[].approvalReset- Returns to review.
samples[].before- Changed fields before.
samples[].id- Item.
samples[].name- Name.
samples[].published- Becomes a pending revision.
snapshotToken- Pass to apply; pins the resolved item set.
unchanged- Items already as the operations ask.
curl -X POST "$PLUTO_API/ad-sets/bulk/preview" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"operations": [
{}
],
"selector": {}
}'Update an ad set
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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- Delivery end, like start; "" runs without an end date.
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
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.
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 PATCH "$PLUTO_API/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 02242215-d5b6-4d7a-932d-3c71f8147d17" \
-H "Content-Type: application/json" \
-d '{
"end": "2026-09-30T13:00:00Z",
"expectedVersion": 3,
"name": "Broad, United States",
"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"
}
}
}'Delete an ad set
Its ads become ungrouped. One deleted at its platform (e.g. in its ads manager) is archived instead (archived: true), with the ads deleted with it. 409 while the ad set (or an ad published in it) is live on its ad platform: pause it, or delete it there (POST /ad-sets/{id}/platform-delete).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set's ID. |
expectedVersion | string | Optional | Version. |
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: fe0dfd18-3bfd-4103-ae9f-46d15cfc5c49"Change a live ad set's bid
The bid of a launch's live ad set, for its bidding strategy: on Meta the bid cap, cost per result goal or ROAS goal of the strategy the launch's campaign sets; where the ad set holds its own bidding, the amount its strategy takes (a platform without a ROAS goal refuses roasGoal; one that bids by itself takes no bid). bidStrategy is refused here: change the strategy in the draft and publish it. The draft changes and exactly that value is published.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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
bidAmount- The amount the ad set's bidding strategy takes, in the ad account currency: on Meta the bid cap or cost per result goal (with COST_CAP and LOWEST_COST_WITH_BID_CAP).
bidStrategy- Optional, Meta only: switch the bid strategy too (ad sets with their own budget, not in a launch). Highest volume, cost per result goal, bid cap or ROAS goal.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS roasGoal- Meta's ROAS goal, e.g. "2.5": at most four decimals, 0.01 to 1000 (with LOWEST_COST_WITH_MIN_ROAS).
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
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.
- 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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/bid" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c9820190-ee33-471a-bde7-e0be3f47cef7" \
-H "Content-Type: application/json" \
-d '{
"bidAmount": "25.00",
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"roasGoal": "150.00"
}'Change an ad set's budget
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/budget" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d49e4eea-370b-493e-bb44-0f81f98436f1" \
-H "Content-Type: application/json" \
-d '{
"amount": "150.00"
}'Duplicate a launch's live ad set
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 ad set'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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/copies" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7d214f47-5478-4269-a4b2-7cb0937bb221" \
-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"
}'Duplicate an ad set
Duplicate an ad set with its ads, here or into another launch.
How an ad set moves between launches of one platform (another platform's launch is a 422): a published ad set can't move to another campaign. The copy keeps what the original shows; in another ad account, what belongs to one ad account follows the destination (on Meta pixel, custom audiences and identity; on a platform with its own launch settings its conversions, lead form, Page and audiences, named in leftOut). Copied ads start a new review.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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
launchId- Destination launch; the same launch when omitted.
name- Name of the copy.
Response
adIds- The copied ads.
adSet- An ad set. Stores explicit overrides only; empty means inherit from the launch.
adSet.effective- The launch settings with the overrides on top.
adSet.externalKey- Your own key.
adSet.id- ID.
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.
adSet.invalid[].field- JSON-pointer-like path, as a refusal names it.
adSet.invalid[].message- Problem.
adSet.launchId- Launch.
adSet.name- Name.
adSet.overrides- Only the launch settings this ad set changes.
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). adSet.position- Order.
adSet.targeting- The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
adSet.version- Increments on every change; send as
expectedVersion. leftOut- In another ad account, on a platform with its own launch settings: the original's settings that belong to its ad account and stayed behind. Absent when none.
skippedAdIds- Ads that couldn't be copied.
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/duplicate" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a6c310b2-be44-4401-a39d-7a77c1aad844" \
-H "Content-Type: application/json" \
-d '{
"launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560",
"name": "Broad, United States"
}'Delete a live ad set (first route)
Irreversible. The same as POST /ad-sets/{id}/platform-delete, under its first name: deletes the ad set's live ads, then the ad set, on its ad platform, reads each back as deleted and archives it in the launch.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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- Optional: the draft version reviewed.
Response
deletes- What is deleted on the ad platform.
jobId- The job deleting on the ad platform.
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/meta-delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 0e744971-8ad4-4fcc-8040-5f4c47776a72" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Move a live ad set in Meta
Meta can't move a live ad set to another campaign. This copies it (POST /{adset_id}/copies with the campaign) and each of its live ads into the copy, in Meta, and adds the copy with its ads to the published launch launchId (same ad account), linked to the copies. The copy starts paused and is turned on only with activateCopy; its ads keep their own status. original: pause or keep; keeping a delivering original while turning the copy on needs confirmBothDeliver (409 bothDeliver otherwise). budget says what the ad set budgets that deliver total before and after, in the ad account's currency. A retry never copies twice. Meta launches only: another platform's live ad set stays in the campaign it was published in (POST /ad-sets/{id}/copies copies it there).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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
activateCopy- Turn the copy on once it exists (default false).
confirmBothDeliver- Confirms that the original and the copy both deliver.
launchId- The published launch whose campaign the copy goes into.
original- What happens to the original once the copy exists.One of
pause,keep
Response
jobId, the move, original, activateCopy, bothDeliver and budget (currency, amount, period, before and after as {daily, lifetime} decimal strings; null for an ad set on its campaign's budget).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Not live, a launch is publishing, or both would deliver without
confirmBothDeliver. - 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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/meta-move" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d37a84e1-7f6f-476e-b090-4e4a98d2e0de" \
-H "Content-Type: application/json" \
-d '{
"activateCopy": true,
"confirmBothDeliver": true,
"launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560",
"original": "pause"
}'Preview an ad set move
What POST /ad-sets/{id}/meta-move with the same body would do, budgets before and after included; nothing changes and jobId is null.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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
activateCopy- Whether the copy would be turned on.
confirmBothDeliver- Ignored by the preview.
launchId- The published launch whose campaign the copy would go into.
original- What would happen to the original.One of
pause,keep
Response
The move as POST /ad-sets/{id}/meta-move would answer, with jobId null.
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/meta-move/preview" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 70d0729d-556b-463e-98fa-9b94db04fa02" \
-H "Content-Type: application/json" \
-d '{
"activateCopy": true,
"confirmBothDeliver": true,
"launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560",
"original": "pause"
}'Reorder an ad set
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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
beforeIdexpectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/move" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: ccebd0b7-565f-4958-bd7c-688a62bd628b" \
-H "Content-Type: application/json" \
-d '{
"beforeId": "2d6da6a4-f1d1-47c6-a1f6-3a3b32c6e8b7",
"expectedVersion": 3
}'Delete a live ad set
Irreversible. Deletes a launch's live ad set with its live ads on its ad platform (the ads first), reads them back as deleted, then archives them in the launch (history kept). In Meta the same as POST /ad-sets/{id}/meta-delete; on a platform that deletes only drafts outright, anything that ran is set to pending deletion. Pausing is the reversible alternative.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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- Optional: the draft version reviewed.
Response
deletes- What is deleted on the ad platform.
jobId- The job deleting on the ad platform.
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/platform-delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 0cbaf783-a6dd-4ea7-bc86-de62c816cce2" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Restore an archived ad set as a draft
Never published: the same ad set returns. Deleted at its ad platform: a new draft ad set is created with copies of the ads deleted there with it; the original stays archived.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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- Optional: the archived version seen.
Response
adIds- Ads restored with an ad set.
copy- A new draft copy (the original was deleted at its ad platform and stays archived).
entity- What was restored.One of
ad,ad_set id- The draft now on the board: the same ID, or the copy's.
launchId- Launch.
restoredFrom- The archived ad or ad set.
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/restore" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 1710df51-2dd0-4cb2-9cfb-ca5ba58510ae" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Change a live ad set's schedule
Change a live ad set's dates or ad scheduling.
startTime / endTime change the launch's ad set and publish exactly those (a platform that fixes the start once an ad set has started refuses a new start then); schedule sets ad scheduling in Meta (it isn't a launch value, so the launch never sends it back; a platform without ad scheduling refuses it). Send dates and ad scheduling in separate calls.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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
endTime- When it stops; in the future and after the start.
schedule- Meta's ad scheduling: the hours the ad set delivers. Needs a lifetime budget (the ad set's or its campaign's); an empty list turns it off.
schedule[].days- 0 is Sunday … 6 is Saturday.
schedule[].endMinute- Minute of the day it ends, on the hour, at least an hour later (up to 1440).
schedule[].startMinute- Minute of the day it starts, on the hour (0, 60, … 1380).
scheduleTimezone- Meta's ad scheduling: whose time zone the schedule follows (default
viewer).One ofviewer,account startTime- When the ad set starts delivering.
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
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.
- 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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/schedule" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a8da4294-0c3e-45a0-bbc3-a0dfcb954a25" \
-H "Content-Type: application/json" \
-d '{
"endTime": "2026-09-30T13:00:00Z",
"schedule": [
{
"days": [
3
],
"endMinute": 3,
"startMinute": 3
}
],
"scheduleTimezone": "viewer",
"startTime": "2026-09-30T13:00:00Z"
}'Split an ad set over Meta's ad limit
Split an ad set that has more ads than Meta allows.
Meta allows 50 ads per ad set. Splits a Meta ad set into the fewest ad sets it needs, balanced (60 ads become 30 and 30): the new ad sets copy its targeting and settings, are named "{name} 2", "{name} 3" and so on, and sit right after it. The budget is divided across the new ad sets in proportion to their ads; the total stays the same, to the cent. Bid and cost caps are copied unchanged. 409 (reason: below_minimum_budget) when a part would fall below Meta's minimum daily budget: nothing is split, and the message says the budget needed. Published ads stay; drafts move. With 50 or fewer ads nothing changes and adSets is empty. Another platform's ad set isn't split (409, reason: split_not_on_platform): keep each within its limits.adsPerAdSet (GET /platforms).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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 version you last read. A mismatch is a conflict that returns the current entity.
Response
adSet- An ad set. Stores explicit overrides only; empty means inherit from the launch.
adSet.effective- The launch settings with the overrides on top.
adSet.externalKey- Your own key.
adSet.id- ID.
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.
adSet.invalid[].field- JSON-pointer-like path, as a refusal names it.
adSet.invalid[].message- Problem.
adSet.launchId- Launch.
adSet.name- Name.
adSet.overrides- Only the launch settings this ad set changes.
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). adSet.position- Order.
adSet.targeting- The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
adSet.version- Increments on every change; send as
expectedVersion. adSets- The new ad sets, in board 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. movedAdIds- The ads that moved.
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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/split" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: fa70ddec-a9a4-447f-973a-aff88fd7f8b3" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Pause or activate an ad set
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/status" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a0c0172a-7577-4e56-9076-d8a0258adab6" \
-H "Content-Type: application/json" \
-d '{
"status": "ACTIVE"
}'Change a live ad set's targeting
Changes the targeting of a live Meta ad set a launch manages (another platform's ad set changes its audience in platformSettings with PATCH /ad-sets/{id}, published with POST /launches/{id}/revisions/publish): locations (countries), excluded countries, age, gender, placements, custom and lookalike audiences and excluded audiences. Name only what changes; given fields replace the live value. The draft changes first, so a later publish never reverts it, and exactly the changed fields go to Meta through the returned job (then read back). An ad set whose live targeting Pluto can't represent (regions, cities, …) is changed on Meta's own spec instead (appliedThrough: meta). Confirm the change with the person first: it changes who sees the ads.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad set'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
beneficiary- The EU advertiser: who benefits from the ads (with
payer). Needed when the ad set reaches the EU and neither it nor its ad account has one. customAudiences- Custom or lookalike audiences to reach; replaces the list (
[]removes them). detailedExclusions- Only
[], which removes the ad set's detailed targeting exclusions: Meta takes no new ones since Marketing API v22.0 (all versions from 2025-04-21). Exclude custom audiences with excludedAudiences. detailedExclusions[].id- Meta's ID (from search_targeting).
detailedExclusions[].name- Its name (optional, for people reading the change).
detailedExclusions[].type- The kind, as search_targeting returns it.One of
interests,behaviors,life_events,industries,income,family_statuses,work_positions,work_employers,education_schools,education_majors detailedTargeting- Interests, behaviors and demographics (IDs and
typefrom search_targeting) as groups: people must match every group, so each further group narrows the audience. Up to 25 groups of up to 1,000 items. Replaces the live detailed targeting;[]removes it. Ad sets a launch manages take one group of interests. Housing, employment and financial ads take only interests from Meta's approved list. excludedAudiences- Audiences to exclude; replaces the list.
excludedLocations- Where they don't run; replaces the excluded locations (
{}removes them). excludedLocations.cities- Cities, optionally with a radius.
excludedLocations.cities[].distanceUnit- Unit of
radius.One ofmile,kilometer excludedLocations.cities[].key- Meta's city key.
excludedLocations.cities[].radius- Around the city: 10-50 miles or 17-80 kilometers.
excludedLocations.countries- Countries, e.g. ["US", "DK"].
excludedLocations.regions- Regions (states, provinces), up to 200.
excludedLocations.regions[].key- Meta's location key (from Meta's targeting search).
excludedLocations.zips- Postal codes (e.g.
US:94304). excludedLocations.zips[].key- Meta's location key (from Meta's targeting search).
gender- Who by gender.One of
All,Men,Women locations- Where the ads run; replaces every live location. On an ad set a launch manages, use countries here; its regions, cities, postal codes and pins are edit_ad_sets
places, published with the launch. locations.cities- Cities, optionally with a radius.
locations.cities[].distanceUnit- Unit of
radius.One ofmile,kilometer locations.cities[].key- Meta's city key.
locations.cities[].radius- Around the city: 10-50 miles or 17-80 kilometers.
locations.countries- Countries, e.g. ["US", "DK"].
locations.regions- Regions (states, provinces), up to 200.
locations.regions[].key- Meta's location key (from Meta's targeting search).
locations.zips- Postal codes (e.g.
US:94304). locations.zips[].key- Meta's location key (from Meta's targeting search).
maxAge- 13-65 (65 means 65+).
minAge- 13-65.
payer- Who pays for the ads (with
beneficiary), for ads that reach the EU. placementsplacements.advantage- Advantage+ placements: Meta chooses (leave platforms out).
placements.platforms- Manual placements: the platforms.
placements.positions- Positions of the chosen platforms; left out means all of them.
Response
adSetId- The Pluto ad set, when a launch manages it.
appliedThroughdraft: through the launch that manages the ad set;meta: on Meta's own targeting spec.One ofdraft,metaavailableAt- When it runs.
fields- The targeting fields the change names.
jobId- The job making the change in Meta; follow it with wait_for_job.
metaAdSetId- Meta's ad set ID.
specialAdCategories- The campaign's special ad categories the change was checked against.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Not live in Meta, the launch is publishing, the Meta connection needs attention (
reason), or the change makes the ad set reach the EU without the advertiser names Meta requires there (reason: eu_advertiser_required,missing, andfix: where they're set; sendbeneficiaryandpayerwith the change instead). - 422Meta's special ad category rules are enforced before anything is queued: housing, employment and financial products and services ads keep ages 18-65+ and all genders, take no excluded locations, postal codes or small areas, need city radii of at least 15 miles (25 km; 15 km in Europe) and can't use lookalike audiences (Meta retired Special Ad Audiences in 2022, so nothing converts them); social issue, electoral and political ads can't add EU countries. Housing, employment and financial ads also take only interests (Meta's approved list), no behaviors, demographics or detailed exclusions. A refusal is a
422naming the field. New detailed targeting exclusions are refused for every ad set (Meta stopped taking them in Marketing API v22.0);detailedExclusions: []removes existing ones. - 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/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753/targeting" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 68123001-1de9-4406-8d1e-51c4324b5441" \
-H "Content-Type: application/json" \
-d '{
"beneficiary": "Brevanne, Inc.",
"customAudiences": [
"Brevanne"
],
"detailedExclusions": [
{
"id": "1663c055-be5e-43a9-b231-83903ab9bbfa",
"name": "Vitamin C Serum, UGC 9x16",
"type": "interests"
}
],
"detailedTargeting": [
[
{
"id": "1663c055-be5e-43a9-b231-83903ab9bbfa",
"name": "Vitamin C Serum, UGC 9x16",
"type": "interests"
}
]
],
"excludedAudiences": [
"Brevanne"
],
"excludedLocations": {
"cities": [
{
"distanceUnit": "mile",
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA",
"radius": 3
}
],
"countries": [
"US"
],
"regions": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
],
"zips": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
]
},
"gender": "All",
"locations": {
"cities": [
{
"distanceUnit": "mile",
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA",
"radius": 3
}
],
"countries": [
"US"
],
"regions": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
],
"zips": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
]
},
"maxAge": 3,
"minAge": 3,
"payer": "Brevanne, Inc.",
"placements": {
"advantage": true,
"platforms": [
"facebook"
],
"positions": [
"platform.position"
]
}
}'