Ads
Search, edit and move ads, and control live ones.
Search ads across launches
Ads in every unarchived launch, newest first (order=oldest: oldest first). A server-queried collection that pages; q matches names literally.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
labelId | string | Optional | Carrying this label. |
statusId | string | Optional | In this review status. |
assigneeId | string | Optional | Assigned to this member. |
mediaId | string | Optional | Whose creative is this media item. |
q | string | Optional | Name contains. |
launchId | string | Optional | Only this launch's ads. |
adSetId | string | Optional | Only this ad set's ads. |
order | string | Optional | newest (default) or oldest: the order the ads were made in. |
after | string | Optional | Cursor. |
limit | string | Optional | 1-200 (default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Ads.
items[].adSetIditems[].assigneeIditems[].createdAt- When the ad was made in Pluto.
items[].id- Ad.
items[].launchId- Launch.
items[].launchName- Launch name.
items[].launchStatus- Launch status.
items[].mediaIditems[].name- Name.
items[].statusIditems[].version- The ad's version: send it as
expectedVersionto change the ad. nextAfter
curl "$PLUTO_API/ads" \
-H "Authorization: Bearer $PLUTO_KEY"Apply a previewed bulk edit of ads
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- The previewed 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/ads/bulk/apply" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 1630a08d-f2a3-46af-89cc-e49c7d5a92f4" \
-H "Content-Type: application/json" \
-d '{
"operations": [
{}
],
"snapshotToken": "hPu4lXSXE27KMmF240dvBsz6amLEuPSGYLiWnzJy"
}'Preview a bulk edit of ads
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/ads/bulk/preview" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"operations": [
{}
],
"selector": {}
}'Move ads
Move ads to an ad set, or to another launch.
With launchId, draft ads move to that launch with their comments, activity, labels and followers, keeping what they show. Published ads can't move (409).
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
adIds- Ads.
adSetIdads- Ads with versions.
beforeIdlaunchId- Destination launch; the ad set must be in it.
Response
Moved ads.
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/ads/move" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 59ac3526-25e6-4808-b27a-e79d13e8ef48" \
-H "Content-Type: application/json" \
-d '{
"adIds": [
"a96d7456-dc02-4734-998b-3e439361abe3"
],
"adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
"ads": [
{}
],
"beforeId": "2d6da6a4-f1d1-47c6-a1f6-3a3b32c6e8b7",
"launchId": "2046ac37-4775-4757-9ef2-3d948cbfc560"
}'Update an ad
Name, ad set, creative, review status, assignee, labels and setting overrides. Changing only statusId (approving or requesting changes) needs just the review permission.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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
adSetIdassigneeIdedit- An edit in effective values (copy, CTA, URL, identity, creative settings), applied after
overrides. Values the editor never offers (a call to action off the list, an enhancement the format lacks) are a 422. edit.bestCardsFirst- A carousel shows its best-performing cards first (default true). Meta only.
edit.cards- A carousel ad's cards, all of them in order (2 to 10); replaces the ad's cards. On Meta an ad with cards is a carousel (each card an image or video; the ad's call to action goes on every card, its URL is the "See more" link and the link of a card without its own). On platforms that set the format per ad set, only an ad set whose format is a carousel takes them.
edit.cards[].description- The card's description, where the platform shows one.
edit.cards[].headline- The card's headline.
edit.cards[].mediaId- The card's image or video: a media library ID. The first card's is the ad's media.
edit.cards[].url- The page the card opens (https://…).
edit.creative- Creative settings.
edit.creative.catalogItems- Show products from your catalog.
edit.creative.features- Advantage+ creative enhancements per format (each is opt-in).
edit.creative.features.carousel- Carousel ads: an enhancement ID to true (turn on) or false (turn off): text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), profile_card (Profile end card), description_automation (Dynamic description).
edit.creative.features.image- Image ads: an enhancement ID to true (turn on) or false (turn off): text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), adapt_to_placement (Adapt to placement), image_touchups (Visual touch-ups), image_templates (Add overlays), image_brightness_and_contrast (Adjust brightness and contrast), image_animation (Image animation), image_background_gen (Generate backgrounds), image_uncrop (Expand image), music (Add music).
edit.creative.features.video- Video ads: an enhancement ID to true (turn on) or false (turn off): text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), video_auto_crop (Adjust aspect ratio), video_uncrop (Expand video), video_filtering (Video filters).
edit.creative.multiAdvertiser- Multi-advertiser ads.
edit.creative.placementCrops- Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of
off,center edit.creative.productSetId- Catalog product set: its numeric Meta ID.
edit.cta- Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of
Apply now,Book now,Buy now,Buy tickets,Contact us,Donate now,Download,Get offer,Get promotions,Get quote,Get showtimes,Learn more,Listen now,Order now,Play game,Request time,See more,Shop now,Sign up,Subscribe,Watch more,No button edit.description- Description.
edit.displayLink- Meta: the link the ad shows instead of its website's domain (Ads Manager's Display link); "" removes it.
edit.endCard- A carousel ends with a card showing the Page (default true). Meta only.
edit.headline- Headline.
edit.identity- The Page and Instagram account the ad publishes as.
edit.identity.instagram- Instagram account: its Meta ID; usually the one linked to the Page.
edit.identity.page- Facebook Page: its numeric Meta ID (get_meta_integration).
edit.imageCrops- An image ad's own crop per shape, in the image's pixels (get_media gives its width and height): 1:1 for every placement outside the groups, 4:5 for Feeds, 9:16 for Stories and Reels, 1.91:1 for right column and search. Each box stays inside the image with its shape's proportions, to the pixel. Shapes left out keep theirs; null puts one back in the middle. A box makes the ad crop (creative.placementCrops center). A new image drops the ad's crops.
edit.imageCrops.1.91:1edit.imageCrops.1.91:1.heightedit.imageCrops.1.91:1.widthedit.imageCrops.1.91:1.x- Left edge, in pixels from the image's left.
edit.imageCrops.1.91:1.y- Top edge, in pixels from the image's top.
edit.imageCrops.1:1edit.imageCrops.1:1.heightedit.imageCrops.1:1.widthedit.imageCrops.1:1.x- Left edge, in pixels from the image's left.
edit.imageCrops.1:1.y- Top edge, in pixels from the image's top.
edit.imageCrops.4:5edit.imageCrops.4:5.heightedit.imageCrops.4:5.widthedit.imageCrops.4:5.x- Left edge, in pixels from the image's left.
edit.imageCrops.4:5.y- Top edge, in pixels from the image's top.
edit.imageCrops.9:16edit.imageCrops.9:16.heightedit.imageCrops.9:16.widthedit.imageCrops.9:16.x- Left edge, in pixels from the image's left.
edit.imageCrops.9:16.y- Top edge, in pixels from the image's top.
edit.placementMedia- Another image or video (a media library ID) for a group of placements, Meta only: feeds (Facebook and Instagram feeds, profile feeds, Explore home, Threads; 4:5), stories (Stories and Reels; 9:16), rightColumn (right column and search results; 1.91:1). The ad's own file shows everywhere else. An image ad takes images and a video ad videos (Meta takes one kind per ad); never a carousel. Groups left out keep theirs; null removes one.
edit.placementMedia.feedsedit.placementMedia.rightColumnedit.placementMedia.storiesedit.text- Primary text.
edit.url- Website URL the ad links to (https://…).
edit.useLaunch- Follow the launch again for these groups, before the rest of the edit: copy (text, headline, description), destination (CTA, URL, the ad's own URL parameters and display link), identity (Page and Instagram), creativeSettings (enhancements, multi-advertiser, catalog, placementCrops).
edit.utm- Meta: the ad's own URL parameters (Ads Manager's per-ad URL parameters, like utm_content={{ad.name}}); the launch's
utmvalue follows the launch again, "" sends none. expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
labelIds- Replace all labels.
labelsadd/removelabel IDs.mediaId- Creative: an image or a video; the ad's
formatfollows it. On a live ad the change is a revision that publishes a new creative, which Meta reviews again. name- Name.
overrides- Replaces the stored overrides (values equal to the launch's collapse to inherit). An unknown key is a 422 naming it (
overrides.<key>). overrides.bestCardsFirstfalsewhen a carousel keeps its card order (default true). Meta only.overrides.cards- A carousel ad's cards, in order.
overrides.cards[].description- The card's description, where the platform shows one.
overrides.cards[].headline- The card's headline.
overrides.cards[].mediaId- The card's image or video: a media library ID. The first card's is the ad's media.
overrides.cards[].url- The page the card opens (https://…).
overrides.copyVariations- Copy lists this ad changes; a list left out follows the launch.
overrides.copyVariations.descriptions- Description; publishing sends one.
overrides.copyVariations.headlines- Headline; publishing sends one.
overrides.copyVariations.primaryTexts- Primary text; publishing sends one.
overrides.creativeSettings- Creative settings this ad changes.
overrides.creativeSettings.catalogItems- Catalog items.
overrides.creativeSettings.creative- Advantage+ creative enhancements per format (each is opt-in).
overrides.creativeSettings.creative.carousel- Carousel ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), profile_card (Profile end card), description_automation (Dynamic description).
overrides.creativeSettings.creative.image- Image ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), adapt_to_placement (Adapt to placement), image_touchups (Visual touch-ups), image_templates (Add overlays), image_brightness_and_contrast (Adjust brightness and contrast), image_animation (Image animation), image_background_gen (Generate backgrounds), image_uncrop (Expand image), music (Add music).
overrides.creativeSettings.creative.video- Video ads: the Advantage+ creative enhancements turned on: text_optimizations (Text improvements), enhance_cta (Enhance CTA), text_translation (Translate text), inline_comment (Relevant comments), site_extensions (Site links), video_auto_crop (Adjust aspect ratio), video_uncrop (Expand video), video_filtering (Video filters).
overrides.creativeSettings.multiAdvertiser- Multi-advertiser ads.
overrides.creativeSettings.placementCrops- Image ads cropped for each placement, so no placement shows bars or a padded background: center crops every image ad to each placement's shape (Feeds 4:5; Stories and Reels 9:16; right column and search 1.91:1; every other placement 1:1), in the middle unless an ad sets its own crop (imageCrops); off sends images as they are. Each crop publishes as a file of its own per group of placements (Meta's placement asset customization), so an ad set optimized for post engagement can't crop. To let Meta crop and expand images instead, turn on image_touchups (Visual touch-ups) in creative.image.One of
off,center overrides.creativeSettings.productSetId- Product set ID.
overrides.cta- Call to action button, as the label people see (Shop now, Learn more, Sign up, …; No button for none).One of
Apply now,Book now,Buy now,Buy tickets,Contact us,Donate now,Download,Get offer,Get promotions,Get quote,Get showtimes,Learn more,Listen now,Order now,Play game,Request time,See more,Shop now,Sign up,Subscribe,Watch more,No button overrides.endCardfalsewhen a carousel has no end card (default true). Meta only.overrides.identity- Page and Instagram account IDs; null follows the launch.
overrides.identity.instagramoverrides.identity.pageoverrides.imageCrops- The ad's own crop per shape, in its image's pixels; shapes left out are cropped in the middle while the ad crops.
overrides.imageCrops.1.91:1overrides.imageCrops.1.91:1.heightoverrides.imageCrops.1.91:1.widthoverrides.imageCrops.1.91:1.x- Left edge, in pixels from the image's left.
overrides.imageCrops.1.91:1.y- Top edge, in pixels from the image's top.
overrides.imageCrops.1:1overrides.imageCrops.1:1.heightoverrides.imageCrops.1:1.widthoverrides.imageCrops.1:1.x- Left edge, in pixels from the image's left.
overrides.imageCrops.1:1.y- Top edge, in pixels from the image's top.
overrides.imageCrops.4:5overrides.imageCrops.4:5.heightoverrides.imageCrops.4:5.widthoverrides.imageCrops.4:5.x- Left edge, in pixels from the image's left.
overrides.imageCrops.4:5.y- Top edge, in pixels from the image's top.
overrides.imageCrops.9:16overrides.imageCrops.9:16.heightoverrides.imageCrops.9:16.widthoverrides.imageCrops.9:16.x- Left edge, in pixels from the image's left.
overrides.imageCrops.9:16.y- Top edge, in pixels from the image's top.
overrides.placementMedia- Another image or video per group of placements (feeds, stories, rightColumn), by media library ID; the ad's own file shows everywhere else.
overrides.placementMedia.feedsoverrides.placementMedia.rightColumnoverrides.placementMedia.storiesoverrides.url- Website URL.
overridesPatch- An RFC 7396 merge patch of the stored overrides: changes only the keys it names (
nullfollows the launch again), so edits to different fields by different people both apply. Send eitheroverridesoroverridesPatch. An unknown key is a 422 naming it (overridesPatch.<key>). statusId- Review status.
Response
adSetId- Ad set; null is ungrouped.
assigneeId- Assignee.
createdAt- Created.
creativeLinkId- Shared with the ads copied from or to it in its launch group's other campaigns (
GET /ads/{id}/linked). crops- Meta: an image ad that crops for each placement, the box of each shape it publishes with (1:1, 4:5, 9:16, 1.91:1), in its image's pixels: its own, else the middle. Absent when it doesn't crop or its image isn't measured yet.
effective- The content the ad publishes: overrides, otherwise the launch's values.
externalKey- Your own key.
format- Creative format:
audiois an audio ad, where the platform has them;textis an ad with no file, no cards and no existing post (an X text Post, a Google or Microsoft search ad, a Reddit free-form ad; where the platform's ads need a file, it is still to come).One ofimage,video,carousel,audio,text id- ID.
issues- Problems with the effective content.
labelIds- Labels.
launchId- Launch.
mediaId- Creative.
name- Name.
overrides- Only what this ad changes.
position- Order.
statusId- Review status.
updatedAt- Last change.
version- Increments on every change; send as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/ads/a96d7456-dc02-4734-998b-3e439361abe3" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7d0690f6-4cab-4f2a-80c2-804691bbbb67" \
-H "Content-Type: application/json" \
-d '{
"adSetId": "dee201f4-1aee-4807-a122-f5e3b69d0753",
"assigneeId": "1ad53f36-b81b-4e8f-9231-32950ee3d9e2",
"edit": {
"bestCardsFirst": true,
"cards": [
{
"description": "Two drops every morning for brighter, even skin.",
"headline": "Brighter skin in 14 days",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
],
"creative": {
"catalogItems": true,
"features": {
"carousel": {
"description_automation": true,
"enhance_cta": true,
"inline_comment": true,
"profile_card": true,
"site_extensions": true,
"text_optimizations": true,
"text_translation": true
},
"image": {
"adapt_to_placement": true,
"enhance_cta": true,
"image_animation": true,
"image_background_gen": true,
"image_brightness_and_contrast": true,
"image_templates": true,
"image_touchups": true,
"image_uncrop": true,
"inline_comment": true,
"music": true,
"site_extensions": true,
"text_optimizations": true,
"text_translation": true
},
"video": {
"enhance_cta": true,
"inline_comment": true,
"site_extensions": true,
"text_optimizations": true,
"text_translation": true,
"video_auto_crop": true,
"video_filtering": true,
"video_uncrop": true
}
},
"multiAdvertiser": true,
"placementCrops": "off",
"productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
},
"cta": "Apply now",
"description": "Two drops every morning for brighter, even skin.",
"displayLink": "Brevanne",
"endCard": true,
"headline": "Brighter skin in 14 days",
"identity": {
"instagram": "Brevanne",
"page": "Brevanne"
},
"imageCrops": {
"1.91:1": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
},
"1:1": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
},
"4:5": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
},
"9:16": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
}
},
"placementMedia": {
"feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
"rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
"stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
},
"text": "Can we try the 4x5 cut for Instagram feed before we publish?",
"url": "https://brevanne.com/products/vitamin-c-serum",
"useLaunch": [
"copy"
],
"utm": "https://brevanne.com/products/vitamin-c-serum"
},
"expectedVersion": 3,
"labelIds": [
"3b3e38bc-b355-4d75-a044-270c99d48ced"
],
"labels": {},
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
"name": "Vitamin C Serum, UGC 9x16",
"overrides": {
"bestCardsFirst": true,
"cards": [
{
"description": "Two drops every morning for brighter, even skin.",
"headline": "Brighter skin in 14 days",
"mediaId": "04acd56b-ded4-4670-9f9b-1c0c550c1701",
"url": "https://brevanne.com/products/vitamin-c-serum"
}
],
"copyVariations": {
"descriptions": [
"Two drops every morning for brighter, even skin."
],
"headlines": [
"Brighter skin in 14 days"
],
"primaryTexts": [
"Our Vitamin C Serum brightens dull skin in 14 days. Free shipping on orders over $50."
]
},
"creativeSettings": {
"catalogItems": true,
"creative": {
"carousel": [
"text_optimizations"
],
"image": [
"text_optimizations"
],
"video": [
"text_optimizations"
]
},
"multiAdvertiser": true,
"placementCrops": "off",
"productSetId": "746ed322-1e3f-49a3-b98b-4e87dd06b4bd"
},
"cta": "Apply now",
"endCard": true,
"identity": {
"instagram": "Brevanne",
"page": "Brevanne"
},
"imageCrops": {
"1.91:1": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
},
"1:1": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
},
"4:5": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
},
"9:16": {
"height": 1920,
"width": 1080,
"x": 3,
"y": 3
}
},
"placementMedia": {
"feeds": "ca58b5f9-a8c3-48aa-8192-05ebabe9df73",
"rightColumn": "a8991bfa-952d-44f1-a7a1-d81b17874b29",
"stories": "ce668e61-646a-4c61-b754-dc0490b958c7"
},
"url": "https://brevanne.com/products/vitamin-c-serum"
},
"overridesPatch": {},
"statusId": "069ff91e-35e1-4603-afc3-792b04f09624"
}'Delete an ad
An ad with comments or activity, or one deleted at its platform (e.g. in its ads manager), is archived instead (archived: true): it leaves the board, keeps its conversation and can be restored (POST /ads/{id}/restore). 409 while the ad is live on its ad platform: pause it, or delete it there (POST /ads/{id}/platform-delete).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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
id, deleted, and archived: true when it was archived.
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/ads/a96d7456-dc02-4734-998b-3e439361abe3" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: fbb3f456-b22f-477f-8cde-4a864cfee3bf"Duplicate a launch's live ad
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'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/ads/a96d7456-dc02-4734-998b-3e439361abe3/copies" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 357eb8cd-c214-4359-9778-813c2e069dce" \
-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
A copy right after the original, back at the default review status.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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
asDrafted- A new draft ad from the ad as drafted, carrying changes Meta won't make on the live ad, even for an ad that came from Meta (
409when it holds a value managed in Meta).
Response
adSetId- Ad set; null is ungrouped.
assigneeId- Assignee.
createdAt- Created.
creativeLinkId- Shared with the ads copied from or to it in its launch group's other campaigns (
GET /ads/{id}/linked). crops- Meta: an image ad that crops for each placement, the box of each shape it publishes with (1:1, 4:5, 9:16, 1.91:1), in its image's pixels: its own, else the middle. Absent when it doesn't crop or its image isn't measured yet.
effective- The content the ad publishes: overrides, otherwise the launch's values.
externalKey- Your own key.
format- Creative format:
audiois an audio ad, where the platform has them;textis an ad with no file, no cards and no existing post (an X text Post, a Google or Microsoft search ad, a Reddit free-form ad; where the platform's ads need a file, it is still to come).One ofimage,video,carousel,audio,text id- ID.
issues- Problems with the effective content.
labelIds- Labels.
launchId- Launch.
mediaId- Creative.
name- Name.
overrides- Only what this ad changes.
position- Order.
statusId- Review status.
updatedAt- Last change.
version- Increments on every change; send as
expectedVersion.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/ads/a96d7456-dc02-4734-998b-3e439361abe3/duplicate" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8e5c911f-2b4c-4248-95f2-ac72022810f4" \
-H "Content-Type: application/json" \
-d '{
"asDrafted": true
}'List linked ads
The ads linked to this one in its launch group's other campaigns (copied from or to it): each with its campaign's label, platform and ad account, whether it's live, whether it's still identical (same file, text, headline and URL), and what its platform no longer lets change now that it's live (frozen). Guests get none.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
creativeLinkId- The link they share; null when the ad has none.
items- Linked ads.
items[].adAccountId- Its ad account.
items[].adId- The linked ad.
items[].frozen- What its platform no longer lets change.
items[].frozen[].fieldtext,headline,description,urlormedia.items[].frozen[].message- Why it can't change.
items[].identical- Same file, text, headline and URL.
items[].label- Its campaign's name in the launch group.
items[].launchId- Its campaign (a launch).
items[].live- It published.
items[].name- The ad's name.
items[].platform- Its platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/ads/a96d7456-dc02-4734-998b-3e439361abe3/linked" \
-H "Authorization: Bearer $PLUTO_KEY"Update linked ads
Carries this ad's text, headline, description, URL or media over to its linked ads (all, or adIds), each through its own platform's rules: review starts again where reviewed content changes, and a published campaign gets pending changes. What a platform doesn't show, or freezes once an ad is live, is skipped with the reason. Never automatic.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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
adIds- Only these linked ads (default all).
fields- What to carry over (default all).
Response
items- One per linked ad.
items[].adId- The linked ad.
items[].applied- What was carried over.
items[].errors- Why it failed, in its platform's words.
items[].errors[].field- Field.
items[].errors[].message- Why.
items[].platform- Its platform.
items[].skipped- What was left out.
items[].skipped[].field- Field.
items[].skipped[].reason- Why.
items[].status- What happened.One of
updated,skipped,failed
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/ads/a96d7456-dc02-4734-998b-3e439361abe3/linked/update" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 506c0038-e3ea-4ca8-a78d-b9484f9c4a08" \
-H "Content-Type: application/json" \
-d '{
"adIds": [
"a96d7456-dc02-4734-998b-3e439361abe3"
],
"fields": [
"text"
]
}'Delete a live ad (first route)
Irreversible. The same as POST /ads/{id}/platform-delete, under its first name: deletes the ad on its ad platform (in Meta status=DELETED), reads it back as deleted and then archives it in the launch (history kept; GET /launches/{id}/archived). A live ad can't be deleted from the draft otherwise; pausing is the reversible alternative.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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/ads/a96d7456-dc02-4734-998b-3e439361abe3/meta-delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: ddfaf642-8b7f-4ee5-a5ca-df13897362fe" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Move a live ad in Meta
Meta can't move a live ad. After the ad's draft moved to another live ad set of the launch (listed under moves in GET /launches/{id}/revisions), this copies the ad into that ad set in Meta (POST /{ad_id}/copies, new IDs), links the copy as a new ad there and puts the original's draft back where it is live. The copy starts paused and is turned on only with activateCopy. original: pause pauses the original after the copy exists; keep leaves it as it is. Keeping a delivering original while turning the copy on is refused (409 bothDeliver) unless confirmBothDeliver is true, since both would deliver. A retry never copies twice. Discarding the pending adSetId change instead puts the draft back. Meta launches only: another platform's live ad stays in the ad set it was published in (POST /ads/{id}/copies copies it there).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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: it stays paused).
confirmBothDeliver- Confirms that the original and the copy both deliver.
expectedVersion- The ad's draft version you reviewed.
original- What happens to the original once the copy exists.One of
pause,keep
Response
jobId, the move (entity, id, name, providerId, from, to, originalDelivers), original, activateCopy, bothDeliver and budget (null for ads).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Not a pending move, not ready (
reason), or both would deliver withoutconfirmBothDeliver. - 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/ads/a96d7456-dc02-4734-998b-3e439361abe3/meta-move" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: fb80c766-5415-463d-a4b4-fa3671ad455a" \
-H "Content-Type: application/json" \
-d '{
"activateCopy": true,
"confirmBothDeliver": true,
"expectedVersion": 3,
"original": "pause"
}'Get Meta's preview of an ad
Meta's preview of an ad in one placement.
Meta renders the ad as it would show in the placement and answers an iframe URL (src, on www.facebook.com, never Meta's HTML) with the size Meta drew it at; show it sandboxed. source: ad previews the live ad in Meta; source: draft previews the ad's current values (a draft, or edits not published yet), built like publishing builds the creative. Cached for 10 minutes per ad version and placement; ask again after expiresAt. 409 not_previewable with missing (ad_account, page, url, media, media_processing, video_not_uploaded, format, meta_ad, meta_refused) when Meta can't draw it yet (a video must be uploaded to the ad account by publishing first); 409 meta_disconnected, meta_reauthorize or meta_permissions for the Meta connection; 429 when Meta or the workspace's preview budget (30 Meta calls per 5 minutes) is exhausted. Ads of Meta launches only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad's ID. |
placement | string | Optional | facebook_feed, instagram_feed, facebook_story, instagram_story, facebook_reels, instagram_reels or instagram_explore (INSTAGRAM_EXPLORE_GRID_HOME). |
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
adFormat- Meta's
ad_format, e.g. INSTAGRAM_STANDARD. adVersion- The ad version the preview shows.
expiresAt- Ask again after this.
fetchedAt- When Meta drew it.
height- Iframe height Meta drew, in pixels.
placement- The placement.One of
facebook_feed,instagram_feed,facebook_story,instagram_story,facebook_reels,instagram_reels,instagram_explore,facebook_marketplace,facebook_right_column,facebook_instream,instagram_search sourcead: the live ad in Meta;draft: the ad's current values.One ofad,draftsrc- Meta's preview iframe URL.
width- Iframe width Meta drew, in pixels.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Not previewable yet (
details.missing), or the Meta connection needs attention. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/ads/a96d7456-dc02-4734-998b-3e439361abe3/meta-preview" \
-H "Authorization: Bearer $PLUTO_KEY"Delete a live ad
Irreversible. Deletes a launch's live ad on its ad platform and reads it back as deleted, then archives it in the launch (history kept; GET /launches/{id}/archived). In Meta the same as POST /ads/{id}/meta-delete; on a platform that deletes only drafts outright, anything that ran is set to pending deletion (stopped for good). Pausing is the reversible alternative.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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/ads/a96d7456-dc02-4734-998b-3e439361abe3/platform-delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5b065b85-0415-427d-86b6-a44747316230" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Get an ad's platform settings
What the launch's platform keeps per ad beyond its text, link and file, in the fields of the platform's launch settings at the ad level (GET /platforms/{platform}/spec). An ad inherits the launch's platformSettings.ad and stores only the keys it changes. A platform that keeps nothing per ad answers 422.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adId- The ad.
launchId- Its launch.
own- Only the keys this ad changes.
platform- The launch's platform.
settings- The ad's effective platform settings: the launch's
platformSettings.adwith the ad's own keys. version- The version to send as
expectedVersion; 0 while the ad has no keys of its own.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad.
- 422The launch's platform keeps no settings per ad.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/ads/a96d7456-dc02-4734-998b-3e439361abe3/platform-settings" \
-H "Authorization: Bearer $PLUTO_KEY"Change an ad's platform settings
Sets the named keys of the ad's own platform settings; null goes back to the launch's value. Each key is checked by the platform's rules against the ad's own text: a value that doesn't fit is refused with 422 in the platform's words, on its field. Send expectedVersion from the last read; another change in between answers 409 with the current settings.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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 last read.
settings- The keys to set;
nullremoves a key.
Response
adId- The ad.
launchId- Its launch.
own- Only the keys this ad changes.
platform- The launch's platform.
settings- The ad's effective platform settings: the launch's
platformSettings.adwith the ad's own keys. version- The version to send as
expectedVersion; 0 while the ad has no keys of its own.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad.
- 409The ad's settings changed since
expectedVersion(the body carriescurrent), or the launch is being published. - 422A value doesn't fit, or the launch's platform keeps no settings per ad.
- 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/ads/a96d7456-dc02-4734-998b-3e439361abe3/platform-settings" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 92b5c018-9725-40b8-a268-d52fea584636" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"settings": {}
}'Restore an archived ad as a draft
Never published: the same ad returns to the board with its conversation (into its ad set when that is still there). Deleted at its ad platform: a new draft copy is created and the original stays archived with its results. 409 when it isn't archived, a newer version exists, or its name or spec key is taken.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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/ads/a96d7456-dc02-4734-998b-3e439361abe3/restore" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 54e51790-ce71-4e08-9a8b-052eddc3e245" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Pause or activate an ad
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad'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/ads/a96d7456-dc02-4734-998b-3e439361abe3/status" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2acfad23-e889-4e0c-9bf9-510eb956359c" \
-H "Content-Type: application/json" \
-d '{
"status": "ACTIVE"
}'Remove an ad link
Takes the ad out of its link; the others stay linked.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
creativeLinkId- The link they share; null when the ad has none.
items- Linked ads.
items[].adAccountId- Its ad account.
items[].adId- The linked ad.
items[].frozen- What its platform no longer lets change.
items[].frozen[].fieldtext,headline,description,urlormedia.items[].frozen[].message- Why it can't change.
items[].identical- Same file, text, headline and URL.
items[].label- Its campaign's name in the launch group.
items[].launchId- Its campaign (a launch).
items[].live- It published.
items[].name- The ad's name.
items[].platform- Its 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/ads/a96d7456-dc02-4734-998b-3e439361abe3/unlink" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 44be0077-e30f-4fb5-bab9-6bbf38216241"Get what a model sees of an ad
The ad's creative as stills sized for vision models (an image's still, or a video's frames with their timestamps) behind short-lived URLs, with the copy it runs with and, once published on Meta, its Meta ad ID and delivery status. The first view of a video may wait a few seconds while its frames are taken.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The ad's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- The ad account's ID on its platform (act_… on Meta).
adSetId- Ad set.
aspectRatio- As ad specs name it.
copy- The copy it runs with: primaryText, headline, description, callToAction, url; a launch ad adds its variations (primaryTexts, headlines, descriptions).
durationMs- Videos: duration.
effectiveStatus- Delivery in Meta when it's live there.
expiresAt- When the still URLs stop working.
formatimage,videooraudio(an audio ad, where the platform has them).hasAudio- Videos: whether there is a sound track.
id- The Pluto ad ID, or the Meta ad ID.
launchId- Launch.
media- A launch ad's creative.
media.archivedAt- Archived; still counted toward media storage until deleted.
media.byteSize- Size in bytes.
media.contentType- MIME type.
media.createdAt- Added.
media.createdBy- Their ID.
media.createdByKind- Who added it.One of
person,api_key,agent,system media.deletedAt- Deleted by a person: the files are gone and no longer counted.
media.durationMs- Videos and audio files: duration.
media.error- Why processing failed.
media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. media.errorParams- The values
errorCode's sentence names, present exactly when it is. media.folderId- Folder; null for the library root.
media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
media.height- Pixels, once processed.
media.id- ID.
media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio media.name- Name.
media.pageCount- Documents: pages, once processed.
media.processedAt- Processed.
media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. media.sourceUrl- Where an import came from.
media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed media.updatedAt- Last change.
media.version- Increments on every change; send as
expectedVersion. media.warnings- Provider-spec findings that don't block use.
media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).media.warnings[].message- Finding.
media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. media.width- Pixels, once processed.
metaAdId- The ad in Meta, once published there.
name- Name.
note- Why there's nothing (or less) to look at.
sourcelaunch: an ad of a Pluto launch (draft or published);meta: an ad that exists only in Meta.One oflaunch,metastills- In order: one for an image, up to 8 frames for a video.
stills[].at- Videos: the same as a timestamp, e.g.
0:04. stills[].atMs- Videos: where the frame is (ms).
stills[].height- Pixels.
stills[].url- Short-lived URL of the JPEG.
stills[].width- Pixels.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/ads/a96d7456-dc02-4734-998b-3e439361abe3/view" \
-H "Authorization: Bearer $PLUTO_KEY"