API reference

Ad sets

Edit, split and duplicate a launch's ad sets, and change live ones.

POST/ad-sets/bulk/apply

Apply a previewed bulk edit of ad sets

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

operationsarray of objectsRequired
Operations.
snapshotTokenstringRequired
From the preview.

Response200 OK

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/ad-sets/bulk/preview

Preview a bulk edit of ad sets

Permission: write

Parameters

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

Request body

operationsarray of objectsRequired
Operations.
selectorobjectRequired
Filters or explicit ids.

Response200 OK

affectedintegerRequired
Items the selector matched (the snapshot).
approvalResetsintegerRequired
Approved ads whose reviewed content changes, so they return to review.
changedintegerRequired
Items the operations change.
entitystringRequired
What the edit changes.One of ad, ad_set
expiresAtstring (date-time)Required
The snapshot token expires then.
problemsarray of objectsRequired
Every item that would be rejected, with the reason.
problems[].idstring (uuid)Required
Item.
problems[].messagestringRequired
Why it can't be changed.
publishedintegerRequired
Items already created at a provider: their change becomes a pending revision to publish.
rejectedintegerRequired
Items the operations can't apply to (see problems).
samplesarray of objectsRequired
Before/after of the first changed items.
samples[].afterobjectRequired
Changed fields after.
samples[].approvalResetbooleanRequired
Returns to review.
samples[].beforeobjectRequired
Changed fields before.
samples[].idstring (uuid)Required
Item.
samples[].namestringRequired
Name.
samples[].publishedbooleanRequired
Becomes a pending revision.
snapshotTokenstring (uuid)Required
Pass to apply; pins the resolved item set.
unchangedintegerRequired
Items already as the operations ask.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/ad-sets/bulk/preview" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {}
    ],
    "selector": {}
  }'
PATCH/ad-sets/{id}

Update an ad set

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

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

Response200 OK

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

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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/ad-sets/{id}

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).

Permission: writeCommand: send Idempotency-Key

Parameters

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

Response200 OK

Deleted IDs.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/ad-sets/dee201f4-1aee-4807-a122-f5e3b69d0753" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: fe0dfd18-3bfd-4103-ae9f-46d15cfc5c49"
PATCH/ad-sets/{id}/bid

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

bidAmountstring
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).
bidStrategystring
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
roasGoalstring
Meta's ROAS goal, e.g. "2.5": at most four decimals, 0.01 to 1000 (with LOWEST_COST_WITH_MIN_ROAS).

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
The job applying the change; follow it with GET /jobs/{id}.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/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"
  }'
PATCH/ad-sets/{id}/budget

Change an ad set's budget

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

amountstringRequired
In the ad account currency.

Response202 Accepted

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

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/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"
  }'
POST/ad-sets/{id}/copies

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

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

Response202 Accepted

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

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/ad-sets/{id}/duplicate

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

launchIdstring (uuid)
Destination launch; the same launch when omitted.
namestring
Name of the copy.

Response201 Created

adIdsarray of strings (uuid)Required
The copied ads.
adSetobjectRequired
An ad set. Stores explicit overrides only; empty means inherit from the launch.
adSet.effectiveobject
The launch settings with the overrides on top.
adSet.externalKeystring or null
Your own key.
adSet.idstring (uuid)Required
ID.
adSet.invalidarray of objects
Only in a write's answer: values of the ad set (its own or the launch's it inherits) kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
adSet.invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
adSet.invalid[].messagestringRequired
Problem.
adSet.launchIdstring (uuid)
Launch.
adSet.namestring
Name.
adSet.overridesobject
Only the launch settings this ad set changes.
adSet.platformSettingsobject
A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's ({} for Meta).
adSet.positioninteger
Order.
adSet.targetingobject
The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
adSet.versioninteger
Increments on every change; send as expectedVersion.
leftOutarray of strings
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.
skippedAdIdsarray of strings (uuid)
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/ad-sets/{id}/meta-delete

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Optional: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted on the ad platform.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
  }'
POST/ad-sets/{id}/meta-move

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).

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

activateCopyboolean
Turn the copy on once it exists (default false).
confirmBothDeliverboolean
Confirms that the original and the copy both deliver.
launchIdstring (uuid)Required
The published launch whose campaign the copy goes into.
originalstringRequired
What happens to the original once the copy exists.One of pause, keep

Response202 Accepted

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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/ad-sets/{id}/meta-move/preview

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

activateCopyboolean
Whether the copy would be turned on.
confirmBothDeliverboolean
Ignored by the preview.
launchIdstring (uuid)Required
The published launch whose campaign the copy would go into.
originalstringRequired
What would happen to the original.One of pause, keep

Response200 OK

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/ad-sets/{id}/move

Reorder an ad set

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

beforeIdstring (uuid) or null
expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.

Response200 OK

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

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
  }'
POST/ad-sets/{id}/platform-delete

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Optional: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted on the ad platform.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
  }'
POST/ad-sets/{id}/restore

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Optional: the archived version seen.

Response200 OK

adIdsarray of strings (uuid)Required
Ads restored with an ad set.
copybooleanRequired
A new draft copy (the original was deleted at its ad platform and stays archived).
entitystringRequired
What was restored.One of ad, ad_set
idstring (uuid)Required
The draft now on the board: the same ID, or the copy's.
launchIdstring (uuid)Required
Launch.
restoredFromstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
  }'
PATCH/ad-sets/{id}/schedule

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

endTimestring (date-time)
When it stops; in the future and after the start.
schedulearray of objects
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[].daysarray of integersRequired
0 is Sunday … 6 is Saturday.
schedule[].endMinuteintegerRequired
Minute of the day it ends, on the hour, at least an hour later (up to 1440).
schedule[].startMinuteintegerRequired
Minute of the day it starts, on the hour (0, 60, … 1380).
scheduleTimezonestring
Meta's ad scheduling: whose time zone the schedule follows (default viewer).One of viewer, account
startTimestring (date-time)
When the ad set starts delivering.

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
The job applying the change; follow it with GET /jobs/{id}.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/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"
  }'
POST/ad-sets/{id}/split

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).

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

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

Response200 OK

adSetobjectRequired
An ad set. Stores explicit overrides only; empty means inherit from the launch.
adSet.effectiveobject
The launch settings with the overrides on top.
adSet.externalKeystring or null
Your own key.
adSet.idstring (uuid)Required
ID.
adSet.invalidarray of objects
Only in a write's answer: values of the ad set (its own or the launch's it inherits) kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
adSet.invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
adSet.invalid[].messagestringRequired
Problem.
adSet.launchIdstring (uuid)
Launch.
adSet.namestring
Name.
adSet.overridesobject
Only the launch settings this ad set changes.
adSet.platformSettingsobject
A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's ({} for Meta).
adSet.positioninteger
Order.
adSet.targetingobject
The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
adSet.versioninteger
Increments on every change; send as expectedVersion.
adSetsarray of objectsRequired
The new ad sets, in board order.
adSets[].effectiveobject
The launch settings with the overrides on top.
adSets[].externalKeystring or null
Your own key.
adSets[].idstring (uuid)Required
ID.
adSets[].invalidarray of objects
Only in a write's answer: values of the ad set (its own or the launch's it inherits) kept as stored although they don't fit, because the write didn't change them (a write refuses only what it changes). Publishing refuses them until they're changed; the checklist lists them too.
adSets[].invalid[].fieldstringRequired
JSON-pointer-like path, as a refusal names it.
adSets[].invalid[].messagestringRequired
Problem.
adSets[].launchIdstring (uuid)
Launch.
adSets[].namestring
Name.
adSets[].overridesobject
Only the launch settings this ad set changes.
adSets[].platformSettingsobject
A launch on a platform with its own settings: the ad set fields this ad set changes from the launch's ({} for Meta).
adSets[].positioninteger
Order.
adSets[].targetingobject
The ad set's own values: countries, ages, budget (decimal string), bid, schedule, devices, audiences.
adSets[].versioninteger
Increments on every change; send as expectedVersion.
movedAdIdsarray of strings (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
  }'
POST/ad-sets/{id}/status

Pause or activate an ad set

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

statusstringRequired
Delivery.One of ACTIVE, PAUSED

Response202 Accepted

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

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
PATCH/ad-sets/{id}/targeting

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

beneficiarystring
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.
customAudiencesarray of strings
Custom or lookalike audiences to reach; replaces the list ([] removes them).
detailedExclusionsarray of objects
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[].idstringRequired
Meta's ID (from search_targeting).
detailedExclusions[].namestring
Its name (optional, for people reading the change).
detailedExclusions[].typestringRequired
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
detailedTargetingarray of array of objects
Interests, behaviors and demographics (IDs and type from 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.
excludedAudiencesarray of strings
Audiences to exclude; replaces the list.
excludedLocationsobject
Where they don't run; replaces the excluded locations ({} removes them).
excludedLocations.citiesarray of objects
Cities, optionally with a radius.
excludedLocations.cities[].distanceUnitstring
Unit of radius.One of mile, kilometer
excludedLocations.cities[].keystringRequired
Meta's city key.
excludedLocations.cities[].radiusinteger
Around the city: 10-50 miles or 17-80 kilometers.
excludedLocations.countriesarray of strings
Countries, e.g. ["US", "DK"].
excludedLocations.regionsarray of objects
Regions (states, provinces), up to 200.
excludedLocations.regions[].keystringRequired
Meta's location key (from Meta's targeting search).
excludedLocations.zipsarray of objects
Postal codes (e.g. US:94304).
excludedLocations.zips[].keystringRequired
Meta's location key (from Meta's targeting search).
genderstring
Who by gender.One of All, Men, Women
locationsobject
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.citiesarray of objects
Cities, optionally with a radius.
locations.cities[].distanceUnitstring
Unit of radius.One of mile, kilometer
locations.cities[].keystringRequired
Meta's city key.
locations.cities[].radiusinteger
Around the city: 10-50 miles or 17-80 kilometers.
locations.countriesarray of strings
Countries, e.g. ["US", "DK"].
locations.regionsarray of objects
Regions (states, provinces), up to 200.
locations.regions[].keystringRequired
Meta's location key (from Meta's targeting search).
locations.zipsarray of objects
Postal codes (e.g. US:94304).
locations.zips[].keystringRequired
Meta's location key (from Meta's targeting search).
maxAgeinteger
13-65 (65 means 65+).
minAgeinteger
13-65.
payerstring
Who pays for the ads (with beneficiary), for ads that reach the EU.
placementsobject
placements.advantagebooleanRequired
Advantage+ placements: Meta chooses (leave platforms out).
placements.platformsarray of strings
Manual placements: the platforms.
placements.positionsarray of strings
Positions of the chosen platforms; left out means all of them.

Response202 Accepted

adSetIdstring (uuid) or null
The Pluto ad set, when a launch manages it.
appliedThroughstringRequired
draft: through the launch that manages the ad set; meta: on Meta's own targeting spec.One of draft, meta
availableAtstring (date-time)Required
When it runs.
fieldsarray of stringsRequired
The targeting fields the change names.
jobIdstring (uuid)Required
The job making the change in Meta; follow it with wait_for_job.
metaAdSetIdstringRequired
Meta's ad set ID.
specialAdCategoriesarray of stringsRequired
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, and fix: where they're set; send beneficiary and payer with 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 422 naming 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-After seconds. 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"
      ]
    }
  }'