Ad platforms
The ad platforms you can use, their launch settings and targeting, and the LinkedIn connection, and the X connection.
List ad platforms
The ad platforms this workspace can use, each with its own words for the ad account, campaign, ad set, ad and identity levels, what Pluto can do there (capabilities), its structure limits, how its API behaves (api) and what its terms allow (policy). Pass a platform's platform value wherever a route takes platform. Also in MCP as list_platforms.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
platforms[]: platform, version, name, words (adAccount, campaign, adSet, ad, identity; each one and many), capabilities (connect, structure, publish, insights, comments, commentReply, commentHide, commentDelete, leads, changeHistory, loops, keywords, recommendations, assetGroups), limits (adsPerAdSet, adSetsPerCampaign; null when unknown), api (validateOnly, idempotentCreates, statusWebhooks, reportingDaysUtc, attributionPerReport, pacing, insightsLagMinutes) and policy (retention: reportingDays, settingsDays, commentTextHours, commenterProfileHours, afterDisconnectDays, null when kept; aiCommentReplies; memberDataLeavesUi; dataLeavesUi, false where what the platform reports shows in Pluto's own app alone; contentToAi, false where the platform's terms keep files imported from it away from AI, so Creative Memory never reads them). Each platform's loops: what loops and Analytics measure there (metrics, each {id, name} with its name on that platform, only those it reports; lowerIsBetter; defaults with check, threshold, rebalance, rotate and scale; the Agent step's goals, each {id, value} with value none, money, percent or ratio; scale with the targets Scale to target takes and the count it grows on; segments, each {id, name}, what For each segment and a segment check split by there (empty where the platform's breakdowns aren't imported); actionMetrics, whether conditions read any action type (metric:action:<type>, metric:action_value:<type>, metric:cost_per_action:<type>); rules, the settings its loops take and what saving refuses there, each {id, block, setting, allows, refuses, atRun, source}; refusedBlocks, the blocks they don't run, each {block, when, why}). connected[]: the platforms connected here (able to publish, connected, with an active ad account), in the same order. waiting[]: connected platforms whose ad accounts the platform doesn't run ads from yet, each {platform, reason} (X before it approves an account or the account has a payment method that can pay): a launch can be drafted there, publishing waits for the platform. defaultPlatform: what a view opens on when none is chosen: the connected platform used last, else the first connected; null when nothing is connected (never Meta by default).
curl "$PLUTO_API/platforms" \
-H "Authorization: Bearer $PLUTO_KEY"List the ad account's own assets
The assets linked to the ad account itself, which every campaign shows unless it has its own: callouts today (type=callout), read from the platform now.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. |
type | string | Optional | callout (the default). |
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.
data- Every callout linked to the ad account.
data[].id- The asset's ID at the platform: what removing it names.
data[].primaryStatus- Whether it serves, after the platform's review.
data[].status- The link's status, in the platform's words (
ENABLED,PAUSED,Active). data[].text- The callout's text;
nullwithwithheldwhere the platform's terms keep it in Pluto's own app. typecallout.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such page: the platform isn't on for this workspace, or it has no such objects.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/account-assets" \
-H "Authorization: Bearer $PLUTO_KEY"Add an asset to the ad account
Links a new callout to the ad account itself, so every campaign shows it unless the campaign has its own. 1 to 25 characters. The same text again answers the callout already there.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
text- The callout's text, 1 to 25 characters.
typecallout(the default).
Response
id- The asset's ID at the platform: what removing it names.
primaryStatus- Whether it serves, after the platform's review.
status- The link's status, in the platform's words (
ENABLED,PAUSED,Active). text- The callout's text;
nullwithwithheldwhere the platform's terms keep it in Pluto's own app.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403An API key or an outside agent can't change this platform yet, or the caller can't publish.
- 404No such page: the platform isn't on for this workspace, or it has no such objects.
- 409The ad account is read-only for the connected user, or the connection needs attention.
- 422The text doesn't fit.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/account-assets" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 46dca5c3-17d5-4b80-881d-ccf9536d5327" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"text": "Can we try the 4x5 cut for Instagram feed before we publish?",
"type": "callout"
}'Remove an asset from the ad account
Unlinks the callout from the ad account: its campaigns stop showing it. The asset itself stays in the ad account's library. Removing one that's already gone is done.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The account asset's ID. |
adAccountId | string | Optional | The ad account. |
type | string | Optional | callout (the default). |
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
adAccountId- The ad account.
id- The asset.
removed- Always true.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403An API key or an outside agent can't change this platform yet, or the caller can't publish.
- 404No such page: the platform isn't on for this workspace, or it has no such objects.
- 409The ad account is read-only for the connected user.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/account-assets/eb27882e-b6e9-4262-967d-16fb53b11ab8" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8191be9d-7ec9-470e-a1f1-0f47750cb503"Get an ad account's own settings
An ad account's settings as the platform holds them (whichever it keeps of the tax and invoice address, the connected user's contact settings, the account's apps, billing and spend cap, payment methods, pixels and audiences, its currency, time zone and attribution windows, the communities and keywords it excludes, and what its campaigns spend from), read from the platform when asked and never stored, on a platform whose ad accounts keep settings shown this way (404 on any other). They change in the platform's own ads manager. Where the platform's terms keep its data inside Pluto's own app, every value is null and withheld is true on every channel but the app's own session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account, by its ID at the platform. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
account- The ad account's own settings as the platform holds them:
currency,timeZone(reporting days and schedules are in it),attributionType(ALL_CONVERSION,CLICK_THROUGH_CONVERSIONorVIEW_THROUGH_CONVERSION),clickAttributionWindowandviewAttributionWindow(DAY,WEEKorMONTH: the windows its reports count conversions in), the app install campaigns' ownappAttributionType,appClickAttributionWindowandappViewAttributionWindow,excludedCommunitiesandexcludedKeywords(where and next to what the account's ads never run),spendCapType(LIFETIMEwhen the account has a spend cap),pixelPartners(measurement partners it allows),redditorHighlightsDefault,status,kind(MANAGEDorSELF_SERVE) andsuspensionReason. Where the platform holds the ad account's own profile instead:name,company,companyEditable(whether the platform's API may change the company name),status,rejectionReason,role,currency,timeZone,country,industry,address, the contact as the platform shows it (contactName,contactEmail,contactNumber,telephoneNumber, masked),language,description,licenseNumber,accountType(AUCTIONorRESERVATION),balance(the total, a decimal string in its currency),createdAtandownerBusinessCenterId. Null wherewithheld. adAccountId- The ad account.
apps- The mobile apps associated with the ad account, each
{id, appStoreIdentifier, osType, conversionTracking}: what an app campaign's ad group promotes. Null wherewithheld. audiences- Its audiences, each
{id, name, sourceType, size, targetableStatus}. Null wherewithheld. billing- The ad account's billing as the platform holds it:
billingType(IOorREVOLVING),spendCap(its lifetime spend cap in its currency, a decimal string, or null),advertiser,agencyandfundingSourceIds. Null wherewithheld. contact- The connected user's contact settings on the ad account:
notificationEmail,contactPhone,contactPhoneExtension. Null wherewithheld. fundingInstruments- What its campaigns spend from, each
{id, name, currency, creditLimit, billableAmount, start, end, servable, reasonsNotServable, authorizeStatus}, amounts as decimal strings in its currency. Null where the platform refused them (fundingInstrumentsReasonsays why) and wherewithheld. fundingInstrumentsReason- Why
fundingInstrumentsis null when the platform refused it: only an admin of the ad account may read them. fundingSources- The payment methods it spends from, each
{id, kind, status, name, currency, cardType, last4, expires, dailySpendLimit, availableCredit, value, email}with the fields of its kind. Null where the platform refused them (fundingSourcesReasonsays why) and wherewithheld. fundingSourcesReason- Why
fundingSourcesis null when the platform refused it: only an organization's admin may read them. pixels- The pixels and apps it counts conversions with, each
{id, name, kind, status}(kindispixelor the platform's own word for an app). Null wherewithheld. tax- The tax and invoice address as the platform holds them:
taxId,taxCategory,businessRelationship,billTo,invoiceJurisdiction,company,name,email,address(its lines in order). Null where the platform refused it (taxReasonsays why) and wherewithheld. taxReason- Why
taxis null when the platform refused it: only the ad account's administrator may read it. withheld- The platform's terms keep what is read from it inside Pluto's own app: the values are left out here.
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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/account-settings" \
-H "Authorization: Bearer $PLUTO_KEY"Change an ad account's own settings
Changes an ad account's own settings at the platform, where its API takes them (404 on any other platform): how its reports attribute conversions (type and click and view windows, and the app install campaigns' own), the communities and keywords its ads never run in or next to, and whether new eligible ads start with the platform's creator highlights on; or, where the platform keeps the ad account's own profile, its name, company name (where the platform lets its API change it), contact and address. Each field given changes; the rest stay as the platform holds them, and one the platform's API doesn't change (a currency, a time zone, a budget) is a 422 on its field. Needs the connection's permission to change ads and an admin role on the ad account at the platform. The answer is the account's settings read again, as GET gives them; the audit log keeps the new values only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account, by its ID at the platform.
address- The business address its receipts show.
appAttributionType- The app install campaigns' own type.One of
ALL_CONVERSION,CLICK_THROUGH_CONVERSION,VIEW_THROUGH_CONVERSION appClickAttributionWindow- The app install campaigns' own click window.One of
DAY,WEEK,MONTH appViewAttributionWindow- The app install campaigns' own view window.One of
DAY,WEEK,MONTH attributionType- Which conversions its reports count: clicks and views, clicks or views.One of
ALL_CONVERSION,CLICK_THROUGH_CONVERSION,VIEW_THROUGH_CONVERSION clickAttributionWindow- How long after a click a conversion counts.One of
DAY,WEEK,MONTH company- Its company name, where the platform lets its API change it (
companyEditable). contactEmail- Its contact's email.
contactName- Its contact person.
contactNumber- Its contact's phone number.
excludedCommunities- The communities (by name,
r/optional) where its ads never run: the whole list, empty to clear it. excludedKeywords- Keywords that keep its ads out of an auction: the whole list, empty to clear it.
name- The ad account's own name, where the platform keeps its profile.
redditorHighlightsDefault- Whether new eligible ads start with creator highlights on; null for the platform's default.
viewAttributionWindow- How long after a view a conversion counts.One of
DAY,WEEK,MONTH
Response
account- The ad account's own settings as the platform holds them:
currency,timeZone(reporting days and schedules are in it),attributionType(ALL_CONVERSION,CLICK_THROUGH_CONVERSIONorVIEW_THROUGH_CONVERSION),clickAttributionWindowandviewAttributionWindow(DAY,WEEKorMONTH: the windows its reports count conversions in), the app install campaigns' ownappAttributionType,appClickAttributionWindowandappViewAttributionWindow,excludedCommunitiesandexcludedKeywords(where and next to what the account's ads never run),spendCapType(LIFETIMEwhen the account has a spend cap),pixelPartners(measurement partners it allows),redditorHighlightsDefault,status,kind(MANAGEDorSELF_SERVE) andsuspensionReason. Where the platform holds the ad account's own profile instead:name,company,companyEditable(whether the platform's API may change the company name),status,rejectionReason,role,currency,timeZone,country,industry,address, the contact as the platform shows it (contactName,contactEmail,contactNumber,telephoneNumber, masked),language,description,licenseNumber,accountType(AUCTIONorRESERVATION),balance(the total, a decimal string in its currency),createdAtandownerBusinessCenterId. Null wherewithheld. adAccountId- The ad account.
fundingInstruments- What its campaigns spend from, each
{id, name, currency, creditLimit, billableAmount, start, end, servable, reasonsNotServable, authorizeStatus}, amounts as decimal strings in its currency. Null where the platform refused them (fundingInstrumentsReasonsays why) and wherewithheld. fundingInstrumentsReason- Why
fundingInstrumentsis null when the platform refused it: only an admin of the ad account may read them. withheld- The platform's terms keep what is read from it inside Pluto's own app: the values are left out here.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The platform doesn't keep such settings here, or the ad account isn't one Pluto has.
- 409The connection may not change ads, or the member isn't an admin of the ad account at the platform.
- 422A value the platform doesn't take, named on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/account-settings" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 70ba9b8d-8bf4-4cf8-93dd-6c19fd64b583" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"address": "Brevanne",
"appAttributionType": "ALL_CONVERSION",
"appClickAttributionWindow": "DAY",
"appViewAttributionWindow": "DAY",
"attributionType": "ALL_CONVERSION",
"clickAttributionWindow": "DAY",
"company": "Brevanne, Inc.",
"contactEmail": "maya@brevanne.com",
"contactName": "Vitamin C Serum, UGC 9x16",
"contactNumber": "Brevanne",
"excludedCommunities": [
"Brevanne"
],
"excludedKeywords": [
"Brevanne"
],
"name": "Vitamin C Serum, UGC 9x16",
"redditorHighlightsDefault": true,
"viewAttributionWindow": "DAY"
}'Preview published ads
The platform's own previews of up to 25 published ads, by their Pluto ID or their ID on the platform, read from the platform when asked and never stored, on a platform that previews ads this way (422 on platform elsewhere). Where the platform's terms keep its data inside Pluto's own app, url and html are null and withheld is true on every other channel, and the platform isn't asked.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adId | string | Optional | An ad, by its Pluto ID or its ID on the platform; repeatable or comma-separated (1-25). |
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
notFound- IDs that name no published ad of the workspace's on the platform.
note- Where the previews show, when they're withheld.
platform- The platform asked.
previews- One per ad found.
previews[].adAccountId- The ad account.
previews[].adId- The Pluto ad, when a launch made or imported it.
previews[].expiresAt- When the platform's addresses stop working, as the platform writes it; ask again after.
previews[].html- The frame's markup as the platform answered it; null as
url. previews[].opens- How
urlopens:frame, in a frame beside your own drawing;page, as the platform's own page in a tab of its own (the platform refuses frames).One offrame,page previews[].platformAdId- The ad's ID on the platform.
previews[].postId- What the preview shows, by its ID on the platform (the promoted post, the asset group or ad previewed).
previews[].previewType- The kind of preview the platform made, in its own words, where it makes more than one.
previews[].tvUrl- The ad on a TV, where the platform renders that too; null as
url. previews[].url- The address of the frame the platform renders the preview in; null where
withheldor when the platform answered none. previews[].withheld- The platform's terms keep what is read from it inside Pluto's own app (
policy.dataLeavesUioff onGET /platforms): its values here are null. Everywhere but Pluto's own app.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The platform is off for your organization or unknown here.
- 409The platform's connection can't be used now (reconnect it).
- 422No ads, more than 25, or the platform doesn't preview ads here.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/ad-previews" \
-H "Authorization: Bearer $PLUTO_KEY"List a platform's ad sets
A platform's ad sets as Pluto last read them: status, delivery, format, objective, budgets and bid as decimal strings in the account currency (null: none), launchId when a Pluto launch manages one. For Meta, the same page as GET /integrations/meta/ad-sets.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Only this ad account. |
status | string | Optional | Only this status, as the platform reports it (e.g. ACTIVE or PAUSED). |
search | string | Optional | Part of the name, or the exact ID. |
after | string | Optional | Cursor: nextAfter from the previous page. |
limit | string | Optional | Page size, 1-500 (default 200). |
campaignId | string | Optional | Only this campaign's ad sets. |
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
data- This page.
nextAfter- Cursor for the next page; null at the end.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/ad-sets" \
-H "Authorization: Bearer $PLUTO_KEY"List a platform's ads
A platform's ads as Pluto last read them: status and delivery (review or serving hold, as the platform reports it), launchId when a Pluto launch manages one. For Meta, the same page as GET /integrations/meta/ads.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Only this ad account. |
status | string | Optional | Only this status, as the platform reports it (e.g. ACTIVE or PAUSED). |
search | string | Optional | Part of the name, or the exact ID. |
after | string | Optional | Cursor: nextAfter from the previous page. |
limit | string | Optional | Page size, 1-500 (default 200). |
campaignId | string | Optional | Only this campaign's ads. |
adSetId | string | Optional | Only this ad set's ads. |
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
data- This page.
nextAfter- Cursor for the next page; null at the end.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/ads" \
-H "Authorization: Bearer $PLUTO_KEY"Estimate an audience's size
How many people an ad set's audience reaches in one ad account, as the platform estimates it now, on a platform that estimates audiences this way (422 on platform elsewhere). Nothing is stored or changed: the body is the audience to estimate, in the shape the platform's ad sets hold it (GET /platforms/{platform}/spec; where the ad set's settings keep it under targeting, that object). A platform that forecasts delivery too answers a week's delivery ranges (delivery) and the plan's reach curve (plan) beside the audience's size. Where the platform's terms keep its data inside Pluto's own app, min and max are null and withheld is true on every other channel, and the platform isn't asked.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
adSet- With
campaign: the ad group's settings (platformSettings.adSetwith its own keys);audiencereplaces its targeting. A bid strategy that sets a bid also answers the suggested bids (bid). audience- The audience, as an ad set's settings hold it on the platform (
audiencein its spec). campaign- Where the platform forecasts a whole ad group: the campaign's settings (
platformSettings.campaign), so the forecast follows its objective and budget.422on a platform that estimates the audience alone. identity- The identity the ads run as, where an audience of its followers needs it.
Response
adAccountId- The ad account.
bid- Where the platform forecasts a whole ad group whose bid strategy sets a bid: the minimum, low, median and high bids as decimal strings in the ad account's currency; null otherwise and where
withheld. currency- The ad account's currency, where
deliveryorplancarry amounts. delivery- Where the platform also forecasts delivery: a week's ranges (
impressions,clicks,conversions,reach,videoViews,installs, each{min, max}) andtotalAudienceSize; null wherewithheld. estimable- Whether the platform estimates this audience: on some platforms an audience made only of locations, age, gender, language and devices has no estimate.
max- The most people; null as
min. min- The fewest people the platform expects the audience to reach; null when it can't be estimated, or where
withheld. note- Where the estimate shows, when it's withheld.
plan- Where the platform also forecasts a plan: its reach curve per budget and what the plan's own budget projects; null where
withheld. withheld- The platform's terms keep what is read from it inside Pluto's own app (
policy.dataLeavesUioff onGET /platforms): its values here are null. Everywhere but Pluto's own app.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The platform is off for your organization or unknown here.
- 409The platform's connection can't be used now (reconnect it), or the platform refused the estimate.
- 422The audience doesn't fit the platform's, or the platform doesn't estimate audiences here.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audience-estimate" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"adSet": {},
"audience": {},
"campaign": {},
"identity": "Brevanne"
}'List a platform's audiences
The ad account's audiences on a platform that keeps them per ad account and lets Pluto make them (422 on platform elsewhere), read from the platform now: customer lists, website and app audiences, look-alikes and those shared with the account, each with its kind, name, matched size, whether an ad set may target it (usable) and why not (reasons), and the account's do-not-reach list (doNotReach). Where the platform's terms keep its data inside Pluto's own app, everything but the IDs is null with withheld true on every other channel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. |
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.
doNotReach- The ad account's do-not-reach list, when it has one: its people never see the account's ads.
doNotReach.actions- What can be done to it here, where the platform says per audience (
replaceList:PUT …/{id}/members;createLookalike:POST …/audiences/lookalikes); left out whereeditablesays it all, and outside Pluto's own app where the platform's terms keep its data there. doNotReach.description- Its description, when it has one.
doNotReach.editable- Whether people can be added and taken out here, and it renamed and deleted (the ad account's own list).
doNotReach.id- The audience at the platform: what an ad set's audience takes.
doNotReach.kind- A customer list, a company list, the do-not-reach list, website visitors, app users, a look-alike, a combination of other audiences, product viewers and buyers, or another kind; null where
withheld.One ofcustomers,companies,doNotReach,website,app,lookalike,combined,product,other doNotReach.name- Its name; null where
withheld. doNotReach.reasons- The platform's reasons when it can't be targeted (
PROCESSING,TOO_SMALL). doNotReach.size- How many people the platform matched; null while it's matching, below its minimum, or where
withheld. doNotReach.usable- Whether an ad set may target it now; null where
withheld. doNotReach.withheld- The platform's terms keep what is read from it inside Pluto's own app (
policy.dataLeavesUioff onGET /platforms): its values here are null. Everywhere but Pluto's own app. items- Its audiences, newest first.
items[].actions- What can be done to it here, where the platform says per audience (
replaceList:PUT …/{id}/members;createLookalike:POST …/audiences/lookalikes); left out whereeditablesays it all, and outside Pluto's own app where the platform's terms keep its data there. items[].description- Its description, when it has one.
items[].editable- Whether people can be added and taken out here, and it renamed and deleted (the ad account's own list).
items[].id- The audience at the platform: what an ad set's audience takes.
items[].kind- A customer list, a company list, the do-not-reach list, website visitors, app users, a look-alike, a combination of other audiences, product viewers and buyers, or another kind; null where
withheld.One ofcustomers,companies,doNotReach,website,app,lookalike,combined,product,other items[].name- Its name; null where
withheld. items[].reasons- The platform's reasons when it can't be targeted (
PROCESSING,TOO_SMALL). items[].size- How many people the platform matched; null while it's matching, below its minimum, or where
withheld. items[].usable- Whether an ad set may target it now; null where
withheld. items[].withheld- The platform's terms keep what is read from it inside Pluto's own app (
policy.dataLeavesUioff onGET /platforms): its values here are null. Everywhere but Pluto's own app. minMatched- People an audience must match before an ad set may target it.
note- Where the platform's values show, when they're withheld.
platform- The platform asked.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The platform is off for your organization or unknown here.
- 409The platform's connection can't be used now (reconnect it).
- 422A field doesn't fit (a name over 255 characters), or the platform doesn't keep audiences this way.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audiences" \
-H "Authorization: Bearer $PLUTO_KEY"Make an audience
Makes a customer list in the ad account at the platform and fills it with the people given (kind: customers, a name unique in the account), or the account's do-not-reach list (kind: doNotReach, one per account), whose people never see the account's ads, or, where the platform makes them, an audience it fills itself from a definition (kind: website, combined or product). Any number of people a request: Pluto sends them in the platform's batches. The platform matches a list within a few hours; an ad set may target it once it matched the platform's minimum (minMatched on the list).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
adSetIds- For
kind: engagement: the ad sets whose ads people saw or clicked. campaignIds- For
kind: engagement: the ad account's campaigns whose ads people saw or clicked, by their ID on the platform. companies- For a company list (
kind: companies, where the platform makes them): the companies, each with a name, website, email domain or page address. companies[].country- A two-letter country code, helping the match.
companies[].emailDomain- The domain its people's emails use.
companies[].name- The company's name.
companies[].pageUrl- Its company page address on the platform.
companies[].website- Its website (
example.com). customEvents- For
kind: websitewith CUSTOM amongevents: the custom events' names. datasetIds- For
kind: website: the datasets whose events count. definition- For an audience the platform fills itself (
kindwebsite, combined or product, where it makes them): how it's defined; on a change only what it names changes. definition.combinationRules- A combined audience's combinations, in the platform's own shape (the audiences and how they combine), as
detail.combinationRulesshows them; replaced whole. definition.membershipDuration- Days people stay in it (website and product audiences).
definition.productAudienceType- Who a product audience reaches, in the platform's words.
definition.rule- A website audience's rule, in the platform's own shape (its
Typeand conditions), asdetail.ruleshows it; replaced whole. definition.tagId- The site tag that collects the people (website and product audiences).
description- A description (up to 1,000 characters), where the platform keeps one.
engagements- For
kind: engagement: what people did with the ads (IMPRESSIONS, CLICKS, UPVOTES, COMMENT_SUBMISSIONS, VIDEO_STARTED, VIDEO_WATCHED_50_PERCENT, VIDEO_WATCHED_100_PERCENT). events- For
kind: website: the pixel's events people did (PAGE_VISIT, VIEW_CONTENT, SEARCH, ADD_TO_CART, ADD_TO_WISHLIST, PURCHASE, LEAD, SIGN_UP, CUSTOM). excludedEvents- For
kind: website: events whose people are left out. exposureType- For
kind: engagement: saw the ads (default) or clicked them.One ofIMPRESSIONS,CLICKS includedEvents- For
kind: website: the events people did. kind- A customer list (default), a company list where the platform makes them, the do-not-reach list where it keeps one, where the platform makes retargeting audiences here, the people who did a pixel's events on the website (
website) or engaged with campaigns' ads (engagement), or an audience the platform fills from adefinitionwhere it makes them (website,combined,product).One ofcustomers,companies,doNotReach,website,engagement,combined,product lines- Where the platform takes them: pasted lines or a CSV's rows, each value (split at commas, semicolons and tabs) an email, a phone number with its country code or a device ID, told apart by its shape; a header row is left out. Hashed like
people. lookbackDays- How many days back what people did counts: 1 to 90 for website and 1 to 180 for engagement, or 30, 60, 90 or 180 where the platform takes fixed windows (30 when left out).
name- The customer list's name, unique in the ad account (up to 255 characters).
people- The people, each with one or more values. Every value is normalized and hashed (SHA-256) before it leaves Pluto and is never stored; a do-not-reach list takes emails and phone numbers only.
people[].company- The company the person works at, helping a name match.
people[].country- A two-letter country code, helping a name match.
people[].deviceId- A mobile advertising ID (IDFA, AdID) or Android ID.
people[].email- An email address.
people[].firstName- A first name, where the platform matches people by name (with
lastName). people[].handle- A username on the platform, with or without
@. people[].lastName- A last name, with
firstName. people[].phone- A phone number with its country code (
+45 25 73 66 00). people[].title- A job title, helping a name match.
people[].xUserId- A user ID on the platform (digits).
pixelId- For
kind: website: the pixel whose events make the audience (from list_platform_conversions).
Response
accepted- Rows the platform took, where it answers row by row; absent where it doesn't say.
action- What was done (
replaced: the list's people replaced whole, where the platform takes a list whole).One ofcreated,added,removed,replaced,updated,deleted adAccountId- The ad account.
audienceId- The audience at the platform.
given- People the request named.
kind- A customer list, a company list, the do-not-reach list, or an audience the platform fills itself (website visitors, as a retargeting audience of a pixel's or dataset's events or from a site tag's rule, a combination of audiences, product viewers and buyers, a look-alike, people who engaged with campaigns' ads, another kind).One of
customers,companies,doNotReach,website,combined,product,lookalike,engagement,other name- The name the request gave, when it gave one.
note- What happens next.
sent- People sent to the platform (each with at least one value it can match).
skipped- People left out: none of their values could be matched.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The ad account isn't the workspace's, or the platform is off for your organization.
- 409The platform's connection can't be used now (reconnect it), the connected account's role at the platform can't change audiences, the audience is one the platform fills itself, or the platform refused the change (its reason).
- 422A field doesn't fit (a name over 255 characters), or the platform doesn't keep audiences this way.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audiences" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7b4a639f-f486-4527-ac45-eee4404fc49a" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"adSetIds": [
"120240541407845332"
],
"campaignIds": [
"120227168091908311"
],
"companies": [
{
"country": "US",
"emailDomain": "Brevanne",
"name": "Vitamin C Serum, UGC 9x16",
"pageUrl": "https://brevanne.com/products/vitamin-c-serum",
"website": "https://brevanne.com"
}
],
"customEvents": [
"Brevanne"
],
"datasetIds": [
"a1b0ded9-87ad-4039-89d9-7968b9aa5195"
],
"definition": {
"combinationRules": [
{}
],
"membershipDuration": 12,
"productAudienceType": "video",
"rule": {},
"tagId": "9f31d37e-2bee-42ac-bec0-da0ba0081d49"
},
"description": "Two drops every morning for brighter, even skin.",
"engagements": [
"Brevanne"
],
"events": [
"Brevanne"
],
"excludedEvents": [
"Brevanne"
],
"exposureType": "IMPRESSIONS",
"includedEvents": [
"PURCHASE"
],
"kind": "customers",
"lines": [
"Brevanne"
],
"lookbackDays": 7,
"name": "Vitamin C Serum, UGC 9x16",
"people": [
{
"company": "Brevanne, Inc.",
"country": "US",
"deviceId": "04595c67-e668-4700-a590-a07d630dfd76",
"email": "maya@brevanne.com",
"firstName": "Vitamin C Serum, UGC 9x16",
"handle": "Brevanne",
"lastName": "Vitamin C Serum, UGC 9x16",
"phone": "+1 212 555 0148",
"title": "Vitamin C Serum, UGC 9x16",
"xUserId": "f3c145fd-ccef-46d7-9b30-3cb881a6765f"
}
],
"pixelId": "427121139040827"
}'Make a lookalike
Makes a look-alike of an audience of the ad account (createLookalike in its actions) on a platform that makes them from Pluto (elsewhere 422 on platform): people like the source's, in countries and of the size the platform takes; a platform that makes a look-alike from its source alone refuses both. The platform fills it itself; an ad set may target it once the platform has it ready.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
countries- Where the platform takes them: the countries it finds people in.
description- A description, where the platform keeps one.
name- The look-alike's name.
size- Where the platform takes one: how close a match, as the platform counts it.
sourceAudienceId- The audience to find people like.
Response
accepted- Rows the platform took, where it answers row by row; absent where it doesn't say.
action- What was done (
replaced: the list's people replaced whole, where the platform takes a list whole).One ofcreated,added,removed,replaced,updated,deleted adAccountId- The ad account.
audienceId- The audience at the platform.
given- People the request named.
kind- A customer list, a company list, the do-not-reach list, or an audience the platform fills itself (website visitors, as a retargeting audience of a pixel's or dataset's events or from a site tag's rule, a combination of audiences, product viewers and buyers, a look-alike, people who engaged with campaigns' ads, another kind).One of
customers,companies,doNotReach,website,combined,product,lookalike,engagement,other name- The name the request gave, when it gave one.
note- What happens next.
sent- People sent to the platform (each with at least one value it can match).
skipped- People left out: none of their values could be matched.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such audience in the ad account, or the platform is off for your organization.
- 409The platform's connection can't be used now (reconnect it), the connected account's role at the platform can't change audiences, the audience is one the platform fills itself, or the platform refused the change (its reason).
- 422A field doesn't fit (a name over 255 characters), or the platform doesn't keep audiences this way.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audiences/lookalikes" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a8268f9a-3989-447a-905f-8e19f872597b" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"countries": [
"US"
],
"description": "Two drops every morning for brighter, even skin.",
"name": "Vitamin C Serum, UGC 9x16",
"size": 18432000,
"sourceAudienceId": "5c87400e-fd18-4bae-9c92-75c3c085c875"
}'Rename an audience
A new name (unique in the ad account) or description for one of the account's own audiences, and for one the platform fills from a definition a new definition (what it names changes; a rule or the combinations are replaced whole). Ad sets that target it keep it. A platform whose lists are renamed in its own ads manager answers 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The audience's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
definition- For an audience the platform fills itself (
kindwebsite, combined or product, where it makes them): how it's defined; on a change only what it names changes. definition.combinationRules- A combined audience's combinations, in the platform's own shape (the audiences and how they combine), as
detail.combinationRulesshows them; replaced whole. definition.membershipDuration- Days people stay in it (website and product audiences).
definition.productAudienceType- Who a product audience reaches, in the platform's words.
definition.rule- A website audience's rule, in the platform's own shape (its
Typeand conditions), asdetail.ruleshows it; replaced whole. definition.tagId- The site tag that collects the people (website and product audiences).
description- The new description; empty clears it.
name- The new name (up to 255 characters).
Response
accepted- Rows the platform took, where it answers row by row; absent where it doesn't say.
action- What was done (
replaced: the list's people replaced whole, where the platform takes a list whole).One ofcreated,added,removed,replaced,updated,deleted adAccountId- The ad account.
audienceId- The audience at the platform.
given- People the request named.
kind- A customer list, a company list, the do-not-reach list, or an audience the platform fills itself (website visitors, as a retargeting audience of a pixel's or dataset's events or from a site tag's rule, a combination of audiences, product viewers and buyers, a look-alike, people who engaged with campaigns' ads, another kind).One of
customers,companies,doNotReach,website,combined,product,lookalike,engagement,other name- The name the request gave, when it gave one.
note- What happens next.
sent- People sent to the platform (each with at least one value it can match).
skipped- People left out: none of their values could be matched.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such audience in the ad account, or the platform is off for your organization.
- 409The platform's connection can't be used now (reconnect it), the connected account's role at the platform can't change audiences, the audience is one the platform fills itself, or the platform refused the change (its reason).
- 422A field doesn't fit (a name over 255 characters), or the platform doesn't keep audiences this way.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audiences/df37a50e-7428-4995-b581-054802adee8c" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 6e06eead-fd2f-4242-883e-dd3d8384e54b" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"definition": {
"combinationRules": [
{}
],
"membershipDuration": 12,
"productAudienceType": "video",
"rule": {},
"tagId": "9f31d37e-2bee-42ac-bec0-da0ba0081d49"
},
"description": "Two drops every morning for brighter, even skin.",
"name": "Vitamin C Serum, UGC 9x16"
}'Delete an audience
Deletes one of the account's own audiences or the do-not-reach list at the platform, for good. Ad sets that targeted a list reach everyone else their targeting names; the do-not-reach list's people can see the account's ads again. A platform whose lists are deleted in its own ads manager answers 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The audience's ID. |
adAccountId | string | Optional | The ad account. |
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
accepted- Rows the platform took, where it answers row by row; absent where it doesn't say.
action- What was done (
replaced: the list's people replaced whole, where the platform takes a list whole).One ofcreated,added,removed,replaced,updated,deleted adAccountId- The ad account.
audienceId- The audience at the platform.
given- People the request named.
kind- A customer list, a company list, the do-not-reach list, or an audience the platform fills itself (website visitors, as a retargeting audience of a pixel's or dataset's events or from a site tag's rule, a combination of audiences, product viewers and buyers, a look-alike, people who engaged with campaigns' ads, another kind).One of
customers,companies,doNotReach,website,combined,product,lookalike,engagement,other name- The name the request gave, when it gave one.
note- What happens next.
sent- People sent to the platform (each with at least one value it can match).
skipped- People left out: none of their values could be matched.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such audience in the ad account, or the platform is off for your organization.
- 409The platform's connection can't be used now (reconnect it), the connected account's role at the platform can't change audiences, the audience is one the platform fills itself, or the platform refused the change (its reason).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audiences/df37a50e-7428-4995-b581-054802adee8c" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e43c49d4-2c05-4a42-b13b-f2563b04c3a8"Add or remove people
Adds people to a customer list or the do-not-reach list, or takes them out (remove: true, also how an opt-out is honoured). Only the ad account's own lists take people: one the platform fills itself (website, app, look-alike) or another account shared answers 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The audience's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
companies- For a company list (
kind: companies, where the platform makes them): the companies, each with a name, website, email domain or page address. companies[].country- A two-letter country code, helping the match.
companies[].emailDomain- The domain its people's emails use.
companies[].name- The company's name.
companies[].pageUrl- Its company page address on the platform.
companies[].website- Its website (
example.com). people- The people, each with one or more values. Every value is normalized and hashed (SHA-256) before it leaves Pluto and is never stored; a do-not-reach list takes emails and phone numbers only.
people[].company- The company the person works at, helping a name match.
people[].country- A two-letter country code, helping a name match.
people[].deviceId- A mobile advertising ID (IDFA, AdID) or Android ID.
people[].email- An email address.
people[].firstName- A first name, where the platform matches people by name (with
lastName). people[].handle- A username on the platform, with or without
@. people[].lastName- A last name, with
firstName. people[].phone- A phone number with its country code (
+45 25 73 66 00). people[].title- A job title, helping a name match.
people[].xUserId- A user ID on the platform (digits).
remove- Take these people out instead of adding them.
Response
accepted- Rows the platform took, where it answers row by row; absent where it doesn't say.
action- What was done (
replaced: the list's people replaced whole, where the platform takes a list whole).One ofcreated,added,removed,replaced,updated,deleted adAccountId- The ad account.
audienceId- The audience at the platform.
given- People the request named.
kind- A customer list, a company list, the do-not-reach list, or an audience the platform fills itself (website visitors, as a retargeting audience of a pixel's or dataset's events or from a site tag's rule, a combination of audiences, product viewers and buyers, a look-alike, people who engaged with campaigns' ads, another kind).One of
customers,companies,doNotReach,website,combined,product,lookalike,engagement,other name- The name the request gave, when it gave one.
note- What happens next.
sent- People sent to the platform (each with at least one value it can match).
skipped- People left out: none of their values could be matched.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such audience in the ad account, or the platform is off for your organization.
- 409The platform's connection can't be used now (reconnect it), the connected account's role at the platform can't change audiences, the audience is one the platform fills itself, or the platform refused the change (its reason).
- 422A field doesn't fit (a name over 255 characters), or the platform doesn't keep audiences this way.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audiences/df37a50e-7428-4995-b581-054802adee8c/members" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 35c7792d-f032-45bb-8bdf-7437985659f0" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"companies": [
{
"country": "US",
"emailDomain": "Brevanne",
"name": "Vitamin C Serum, UGC 9x16",
"pageUrl": "https://brevanne.com/products/vitamin-c-serum",
"website": "https://brevanne.com"
}
],
"people": [
{
"company": "Brevanne, Inc.",
"country": "US",
"deviceId": "04595c67-e668-4700-a590-a07d630dfd76",
"email": "maya@brevanne.com",
"firstName": "Vitamin C Serum, UGC 9x16",
"handle": "Brevanne",
"lastName": "Vitamin C Serum, UGC 9x16",
"phone": "+1 212 555 0148",
"title": "Vitamin C Serum, UGC 9x16",
"xUserId": "f3c145fd-ccef-46d7-9b30-3cb881a6765f"
}
],
"remove": true
}'Replace a list
Replaces everyone a customer list holds with the people given, on a platform that takes a list whole (replaceList in the audience's actions; elsewhere 422 on platform, and such a platform refuses POST …/members). Every value is normalized and hashed (SHA-256) before it leaves Pluto and is never stored. The platform matches the new list again before an ad set reaches it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The audience's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
lines- Where the platform takes them: pasted lines or a CSV's rows, each value (split at commas, semicolons and tabs) an email, a phone number with its country code or a device ID, told apart by its shape; a header row is left out. Hashed like
people. people- The people, each with one or more values. Every value is normalized and hashed (SHA-256) before it leaves Pluto and is never stored; a do-not-reach list takes emails and phone numbers only.
people[].company- The company the person works at, helping a name match.
people[].country- A two-letter country code, helping a name match.
people[].deviceId- A mobile advertising ID (IDFA, AdID) or Android ID.
people[].email- An email address.
people[].firstName- A first name, where the platform matches people by name (with
lastName). people[].handle- A username on the platform, with or without
@. people[].lastName- A last name, with
firstName. people[].phone- A phone number with its country code (
+45 25 73 66 00). people[].title- A job title, helping a name match.
people[].xUserId- A user ID on the platform (digits).
Response
accepted- Rows the platform took, where it answers row by row; absent where it doesn't say.
action- What was done (
replaced: the list's people replaced whole, where the platform takes a list whole).One ofcreated,added,removed,replaced,updated,deleted adAccountId- The ad account.
audienceId- The audience at the platform.
given- People the request named.
kind- A customer list, a company list, the do-not-reach list, or an audience the platform fills itself (website visitors, as a retargeting audience of a pixel's or dataset's events or from a site tag's rule, a combination of audiences, product viewers and buyers, a look-alike, people who engaged with campaigns' ads, another kind).One of
customers,companies,doNotReach,website,combined,product,lookalike,engagement,other name- The name the request gave, when it gave one.
note- What happens next.
sent- People sent to the platform (each with at least one value it can match).
skipped- People left out: none of their values could be matched.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such audience in the ad account, or the platform is off for your organization.
- 409The platform's connection can't be used now (reconnect it), the connected account's role at the platform can't change audiences, the audience is one the platform fills itself, or the platform refused the change (its reason).
- 422A field doesn't fit (a name over 255 characters), or the platform doesn't keep audiences this way.
- 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 PUT "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/audiences/df37a50e-7428-4995-b581-054802adee8c/members" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 394e2257-ad35-4b65-b586-2ca49efc20f3" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"lines": [
"Brevanne"
],
"people": [
{
"company": "Brevanne, Inc.",
"country": "US",
"deviceId": "04595c67-e668-4700-a590-a07d630dfd76",
"email": "maya@brevanne.com",
"firstName": "Vitamin C Serum, UGC 9x16",
"handle": "Brevanne",
"lastName": "Vitamin C Serum, UGC 9x16",
"phone": "+1 212 555 0148",
"title": "Vitamin C Serum, UGC 9x16",
"xUserId": "f3c145fd-ccef-46d7-9b30-3cb881a6765f"
}
]
}'List portfolio bid strategies
The ad account's bid strategies shared by campaigns, each with its own targets and how many campaigns follow it, and the types a new one takes (types, with their labels), read from the platform now.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. |
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.
data- Every bid strategy that isn't removed.
data[].campaignCount- How many campaigns follow it.
data[].campaignType- Where the platform ties a strategy to one campaign type: the campaigns that may follow it.
data[].currency- The currency of its money targets.
data[].id- The platform's ID: what a launch's
bidding.portfolionames. data[].name- Its name, unique in the ad account;
nullwithwithheldwhere the platform's terms keep it in Pluto's own app (its type, count, currency and targets too). data[].status- Its status at the platform.
data[].targetsdata[].targets.impressionShare- An impression share strategy: percent of impressions to aim for, 1 to 100.
data[].targets.location- An impression share strategy: where on the results page.One of
ANYWHERE_ON_PAGE,TOP_OF_PAGE,ABSOLUTE_TOP_OF_PAGE data[].targets.maxCpc- The highest bid the strategy sets, a decimal in the ad account's currency;
""clears it. data[].targets.minCpc- The lowest bid the strategy sets;
""clears it. data[].targets.targetCpa- The cost per action to aim for, a decimal in the ad account's currency;
""clears it. data[].targets.targetRoas- The return on ad spend to aim for, in percent (
"350"is 350%), 1 to 100,000;""clears it. data[].type- Its type, in the platform's words.
types- The types a new strategy takes.
types[].label- Its name.
types[].value- The type.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such page: the platform isn't on for this workspace, or it has no such objects.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/bid-strategies" \
-H "Authorization: Bearer $PLUTO_KEY"Create a portfolio bid strategy
FINANCIAL once campaigns follow it. Creates a bid strategy campaigns can share, with its own targets: a target CPA, a target ROAS, Maximize conversions or conversion value with an optional target, Maximize clicks with its bid limits, or a target impression share. Each type takes only its own targets (422 names the field). A launch follows it through its bidding's portfolio.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
campaignType- Where the platform ties a strategy to one campaign type: the campaigns that may follow it, fixed once made (
Searchwhen left out); another platform refuses it.One ofSearch,Shopping name- Its name, unique in the ad account.
targetstargets.impressionShare- An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.location- An impression share strategy: where on the results page.One of
ANYWHERE_ON_PAGE,TOP_OF_PAGE,ABSOLUTE_TOP_OF_PAGE targets.maxCpc- The highest bid the strategy sets, a decimal in the ad account's currency;
""clears it. targets.minCpc- The lowest bid the strategy sets;
""clears it. targets.targetCpa- The cost per action to aim for, a decimal in the ad account's currency;
""clears it. targets.targetRoas- The return on ad spend to aim for, in percent (
"350"is 350%), 1 to 100,000;""clears it. type- Its type (a platform that hasn't one of them refuses it on
type).One ofMAXIMIZE_CONVERSIONS,MAXIMIZE_CONVERSION_VALUE,TARGET_CPA,TARGET_ROAS,TARGET_SPEND,TARGET_IMPRESSION_SHARE
Response
campaignCount- How many campaigns follow it.
campaignType- Where the platform ties a strategy to one campaign type: the campaigns that may follow it.
currency- The currency of its money targets.
id- The platform's ID: what a launch's
bidding.portfolionames. name- Its name, unique in the ad account;
nullwithwithheldwhere the platform's terms keep it in Pluto's own app (its type, count, currency and targets too). status- Its status at the platform.
targetstargets.impressionShare- An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.location- An impression share strategy: where on the results page.One of
ANYWHERE_ON_PAGE,TOP_OF_PAGE,ABSOLUTE_TOP_OF_PAGE targets.maxCpc- The highest bid the strategy sets, a decimal in the ad account's currency;
""clears it. targets.minCpc- The lowest bid the strategy sets;
""clears it. targets.targetCpa- The cost per action to aim for, a decimal in the ad account's currency;
""clears it. targets.targetRoas- The return on ad spend to aim for, in percent (
"350"is 350%), 1 to 100,000;""clears it. type- Its type, in the platform's words.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403An API key or an outside agent can't change this platform yet, or the caller can't change budgets and bids.
- 404No such page: the platform isn't on for this workspace, or it has no such objects.
- 409The ad account is read-only for the connected user.
- 422A value doesn't fit, or the name is taken.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/bid-strategies" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e0db57a2-4c35-4cf8-9a8f-f2f7e5c67242" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"campaignType": "Search",
"name": "Vitamin C Serum, UGC 9x16",
"targets": {
"impressionShare": "0.18",
"location": "ANYWHERE_ON_PAGE",
"maxCpc": "150.00",
"minCpc": "Brevanne",
"targetCpa": "150.00",
"targetRoas": "2.84"
},
"type": "MAXIMIZE_CONVERSIONS"
}'Change a portfolio strategy's targets
FINANCIAL. Changes a shared bid strategy's name or its own targets; every campaign that follows it bids by them at once (campaignCount says how many). A target left out stays as it is; an empty text clears it (a platform that keeps a target once it's set refuses an empty one on its field). Its type stays: another type is a new strategy. The answer is the strategy as the platform has it afterwards; the audit log has old and new.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The bid strategy's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
name- A new name.
targetstargets.impressionShare- An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.location- An impression share strategy: where on the results page.One of
ANYWHERE_ON_PAGE,TOP_OF_PAGE,ABSOLUTE_TOP_OF_PAGE targets.maxCpc- The highest bid the strategy sets, a decimal in the ad account's currency;
""clears it. targets.minCpc- The lowest bid the strategy sets;
""clears it. targets.targetCpa- The cost per action to aim for, a decimal in the ad account's currency;
""clears it. targets.targetRoas- The return on ad spend to aim for, in percent (
"350"is 350%), 1 to 100,000;""clears it.
Response
campaignCount- How many campaigns follow it.
campaignType- Where the platform ties a strategy to one campaign type: the campaigns that may follow it.
currency- The currency of its money targets.
id- The platform's ID: what a launch's
bidding.portfolionames. name- Its name, unique in the ad account;
nullwithwithheldwhere the platform's terms keep it in Pluto's own app (its type, count, currency and targets too). status- Its status at the platform.
targetstargets.impressionShare- An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.location- An impression share strategy: where on the results page.One of
ANYWHERE_ON_PAGE,TOP_OF_PAGE,ABSOLUTE_TOP_OF_PAGE targets.maxCpc- The highest bid the strategy sets, a decimal in the ad account's currency;
""clears it. targets.minCpc- The lowest bid the strategy sets;
""clears it. targets.targetCpa- The cost per action to aim for, a decimal in the ad account's currency;
""clears it. targets.targetRoas- The return on ad spend to aim for, in percent (
"350"is 350%), 1 to 100,000;""clears it. type- Its type, in the platform's words.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403An API key or an outside agent can't change this platform yet, or the caller can't change budgets and bids.
- 404No such bid strategy, or no such page for the platform.
- 409The ad account is read-only, or Pluto doesn't change this type of strategy.
- 422A value doesn't fit, or the name is taken.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/bid-strategies/84cf785d-0d45-4887-8d13-498468372564" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 609af2cc-36f6-4724-89d4-3acb67d29c91" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"name": "Vitamin C Serum, UGC 9x16",
"targets": {
"impressionShare": "0.18",
"location": "ANYWHERE_ON_PAGE",
"maxCpc": "150.00",
"minCpc": "Brevanne",
"targetCpa": "150.00",
"targetRoas": "2.84"
}
}'List a platform's campaigns
A platform's campaigns as Pluto last read them from the platform, by ID: budgets as decimal strings in the ad account's currency (null: none, never zero) and launchId when a Pluto launch manages one. For Meta, the same page as GET /integrations/meta/campaigns (adAccountId required).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Only this ad account. |
status | string | Optional | Only this status, as the platform reports it (e.g. ACTIVE or PAUSED). |
search | string | Optional | Part of the name, or the exact ID. |
after | string | Optional | Cursor: nextAfter from the previous page. |
limit | string | Optional | Page size, 1-500 (default 200). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
data- This page.
nextAfter- Cursor for the next page; null at the end.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/campaigns" \
-H "Authorization: Bearer $PLUTO_KEY"List conversion actions
The ad account's conversion actions that aren't removed, each with the tag the platform generated for it where it has one (tagSnippets), read from the platform now; with the types (types: value, label, whether it counts calls and whether the platform answers a tag for it) and categories (categories) a new one takes, in the platform's words.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. |
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.
categories- The categories a new conversion action takes.
categories[].label- Its name.
categories[].value- The category.
data- Every conversion action that isn't removed.
data[].category- Its category, in the platform's words.
data[].id- The platform's ID.
data[].name- Its name, unique in the ad account.
data[].status- Its status at the platform.
data[].tagSnippets- The tag the platform generated, to put on the website; empty for a type that needs none.
data[].tagSnippets[].eventSnippet- The event snippet, for the page that counts the conversion.
data[].tagSnippets[].globalSiteTag- The site-wide tag, for every page of the site.
data[].tagSnippets[].pageFormat- The page's format the snippet is for (
HTML,AMP). data[].tagSnippets[].type- What the snippet tracks, in the platform's words (
WEBPAGE,WEBPAGE_ONCLICK,CLICK_TO_CALL,WEBSITE_CALL). data[].type- Its type, in the platform's words.
types- The types a new conversion action takes.
types[].call- It counts calls.
types[].label- Its name.
types[].tagged- The platform answers a tag to put on the website.
types[].value- The type.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such page: the platform isn't on for this workspace, or it has no such objects.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversion-actions" \
-H "Authorization: Bearer $PLUTO_KEY"Create a conversion action
Creates a conversion action in the ad account, for campaigns to count and bid for: a website's, or one of the call types the platform offers. The platform checks it first (422 on the field in its own words, a name already taken on name); the answer is the action as the platform has it, with the tag it generated to put on the website (tagSnippets). The same request again with the same Idempotency-Key answers the same action, and an action already made under the name by a lost try is the answer. A platform without conversion actions answers 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
alwaysUseDefaultValue- Count
valueeven when the site sends its own (always on for calls from ads and to a website number). callSeconds- Calls: how long a call lasts before it counts, 0 to 10,000 (60 when left out).
category- What it counts, in the platform's words (
PURCHASE,SUBMIT_LEAD_FORM, …);DEFAULTwhen left out. clickThroughDays- How many days after a click a conversion counts: 1 to 90, 1 to 60 for calls.
counting- Every conversion after a click, or only the first.One of
MANY_PER_CLICK,ONE_PER_CLICK name- Its name, unique in the ad account, at most 100 characters.
primary- Used for bidding as a primary action of its goal.
type- A website's, calls from ads, calls to a number on the website, or clicks on a number on the mobile website.One of
WEBPAGE,AD_CALL,WEBSITE_CALL,CLICK_TO_CALL value- What one conversion is worth, in the ad account's currency.
viewThroughDays- How many days after a view a conversion counts: 1 to 30; none for calls.
Response
category- Its category, in the platform's words.
id- The platform's ID.
name- Its name, unique in the ad account.
status- Its status at the platform.
tagSnippets- The tag the platform generated, to put on the website; empty for a type that needs none.
tagSnippets[].eventSnippet- The event snippet, for the page that counts the conversion.
tagSnippets[].globalSiteTag- The site-wide tag, for every page of the site.
tagSnippets[].pageFormat- The page's format the snippet is for (
HTML,AMP). tagSnippets[].type- What the snippet tracks, in the platform's words (
WEBPAGE,WEBPAGE_ONCLICK,CLICK_TO_CALL,WEBSITE_CALL). type- Its type, in the platform's words.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403An API key or an outside agent can't change this platform yet, or the caller can't publish.
- 404No such page: the platform isn't on for this workspace, or it has no such objects.
- 409The ad account is read-only for the connected user, or the connection needs attention.
- 422A value doesn't fit, in the platform's words on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversion-actions" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: aebe0ddc-427c-4551-845b-0b5f0d825a2a" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"alwaysUseDefaultValue": true,
"callSeconds": 12,
"category": "Brevanne",
"clickThroughDays": 7,
"counting": "MANY_PER_CLICK",
"name": "Daily budget",
"primary": true,
"type": "WEBPAGE",
"value": "4210.00",
"viewThroughDays": 7
}'Get a conversion action and its tag
One conversion action of the ad account with the tag the platform generated for it, read from the platform now.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The conversion action's ID. |
adAccountId | string | Optional | The ad account. |
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
category- Its category, in the platform's words.
id- The platform's ID.
name- Its name, unique in the ad account.
status- Its status at the platform.
tagSnippets- The tag the platform generated, to put on the website; empty for a type that needs none.
tagSnippets[].eventSnippet- The event snippet, for the page that counts the conversion.
tagSnippets[].globalSiteTag- The site-wide tag, for every page of the site.
tagSnippets[].pageFormat- The page's format the snippet is for (
HTML,AMP). tagSnippets[].type- What the snippet tracks, in the platform's words (
WEBPAGE,WEBPAGE_ONCLICK,CLICK_TO_CALL,WEBSITE_CALL). type- Its type, in the platform's words.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such conversion action, or no such page for the platform.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversion-actions/ceca8e63-e389-490d-8bdf-6ed1143fa432" \
-H "Authorization: Bearer $PLUTO_KEY"Create a conversion goal
Creates a conversion goal in the account, on a platform whose conversion goals are made from Pluto, checked before the platform is asked; the platform's refusals come back on their fields. Defaults as the platform's own: every conversion counted for 30 days after a click, active, included in Conversions, no value. The same request again with the same Idempotency-Key answers the same goal. It then lists in GET /platforms/{platform}/conversions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The account.
app- App install goals:
platform(Android,iOS,Windows) andstoreId. attributionModel- How credit is given.One of
LastTouch,DataDriven category- The goal's category in the platform's words (
Purchase,Signup, …). conversionWindowMinutes- Minutes after a click a conversion counts: 1 to 129,600 (90 days).
countType- Every conversion, or one per click.One of
All,Unique event- Event goals:
category,actionandlabel(each an operator and expression) andvalue(operator:Equals,LessThan,GreaterThan, andvalue). includeInConversions- Counted in Conversions and used for bidding.
minimumDurationSeconds- Duration goals: how long a visit lasts before it counts.
minimumPagesViewed- Pages per visit goals: how many pages a visit counts from.
name- Its name, unique in the account, at most 100 characters.
revenuetype(FixedValue,VariableValue,NoValue) andvalue, a decimal in the account's currency.scope- The account's own, or every account of its customer.One of
Account,Customer status- Counting, or not.One of
Active,Paused tagId- The site tag that tracks it (URL, duration, pages per visit and event goals).
type- What counts: a destination URL, a visit's duration, pages per visit, a custom event, an app install, offline or in-store conversions. Never changes.One of
Url,Duration,PagesViewedPerVisit,Event,AppInstall,OfflineConversion,InStoreTransaction urloperator(Equals,BeginsWith,RegularExpression,Contains) andexpression.viewThroughWindowMinutes- Minutes after a view a conversion counts: 1 to 43,200 (30 days).
Response
adAccountId- The account.
done- What was done.One of
created,changed id- The goal's or tag's ID at the platform.
platform- The platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The caller can't publish.
- 404No such page: the platform isn't on for this workspace, or it has no conversion goals or site tags.
- 409The connected user can only view the account, or the connection needs attention.
- 422A value doesn't fit, or the platform refused it, said on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversion-goals" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 320789b7-e32f-4184-a0e5-f37f6d0deb37" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"app": {},
"attributionModel": "LastTouch",
"category": "Purchase",
"conversionWindowMinutes": 60,
"countType": "All",
"event": {},
"includeInConversions": true,
"minimumDurationSeconds": 12,
"minimumPagesViewed": 3,
"name": "Vitamin C Serum, UGC 9x16",
"revenue": {},
"scope": "Account",
"status": "Active",
"tagId": "9f31d37e-2bee-42ac-bec0-da0ba0081d49",
"type": "Url",
"url": {},
"viewThroughWindowMinutes": 60
}'Change a conversion goal
Changes only what the body names of a conversion goal; its type never changes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The conversion goal's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The account.
app- App install goals:
platform(Android,iOS,Windows) andstoreId. attributionModel- How credit is given.One of
LastTouch,DataDriven category- The goal's category in the platform's words (
Purchase,Signup, …). conversionWindowMinutes- Minutes after a click a conversion counts: 1 to 129,600 (90 days).
countType- Every conversion, or one per click.One of
All,Unique event- Event goals:
category,actionandlabel(each an operator and expression) andvalue(operator:Equals,LessThan,GreaterThan, andvalue). includeInConversions- Counted in Conversions and used for bidding.
minimumDurationSeconds- Duration goals: how long a visit lasts before it counts.
minimumPagesViewed- Pages per visit goals: how many pages a visit counts from.
name- Its name, unique in the account, at most 100 characters.
revenuetype(FixedValue,VariableValue,NoValue) andvalue, a decimal in the account's currency.scope- The account's own, or every account of its customer.One of
Account,Customer status- Counting, or not.One of
Active,Paused tagId- The site tag that tracks it (URL, duration, pages per visit and event goals).
type- What counts: a destination URL, a visit's duration, pages per visit, a custom event, an app install, offline or in-store conversions. Never changes.One of
Url,Duration,PagesViewedPerVisit,Event,AppInstall,OfflineConversion,InStoreTransaction urloperator(Equals,BeginsWith,RegularExpression,Contains) andexpression.viewThroughWindowMinutes- Minutes after a view a conversion counts: 1 to 43,200 (30 days).
Response
adAccountId- The account.
done- What was done.One of
created,changed id- The goal's or tag's ID at the platform.
platform- The platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The caller can't publish.
- 404No such conversion goal, or no such page for the platform.
- 409The connected user can only view the account, or the connection needs attention.
- 422A value doesn't fit, or the platform refused it, said on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversion-goals/da7db6f5-b11c-4a82-9d77-da717c287b8b" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 69e7e7a4-81c0-4a25-b4ab-5f3a9e4158bb" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"app": {},
"attributionModel": "LastTouch",
"category": "Purchase",
"conversionWindowMinutes": 60,
"countType": "All",
"event": {},
"includeInConversions": true,
"minimumDurationSeconds": 12,
"minimumPagesViewed": 3,
"name": "Vitamin C Serum, UGC 9x16",
"revenue": {},
"scope": "Account",
"status": "Active",
"tagId": "9f31d37e-2bee-42ac-bec0-da0ba0081d49",
"type": "Url",
"url": {},
"viewThroughWindowMinutes": 60
}'List conversions
The conversions an ad set of the ad account can count, on a platform that defines them per ad account, read from the platform now: each with its id (what an ad set's platformSettings.conversions takes), name, kind (the platform's type, like LEAD or PURCHASE) and enabled, enabled ones first; where the platform's conversion events are made from here, each also has type, status, clickWindow, viewWindow, retargeting, lastTrackedAt and installCode, the code that fires it on the site. Meta counts conversions with the ad set's pixel and event instead (422).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. |
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 and data (each id, name, kind, enabled).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 409The platform's connection can't be used now (reconnect it).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversions" \
-H "Authorization: Bearer $PLUTO_KEY"Create a conversion event
Creates a conversion event in the ad account, on a platform whose conversion events are made from here (another platform answers 422 naming where it's done). Checked first, then made at the platform while the request waits; it then lists in GET /platforms/{platform}/conversions with the code that fires it on the site. Windows not given start at 30 days after a click and 1 day after a view, and retargeting on. On a platform that measures conversions with datasets, type is DATASET, PIXEL (with domain) or CAPI, each made in datasetId or a dataset of its own and shared with the ad account. The connected account must be able to manage the ad account. The answer names IDs only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
advancedMatching- A new pixel's automatic advanced matching.
advancedMatchingFields- The fields a new pixel's advanced matching uses.
clickWindow- Days after a click a conversion counts: 1, 7, 14 or 30.
datasetId- Where conversions are measured with datasets: the dataset a pixel or CAPI integration joins; none: one of its own.
domain- Where conversions are measured with datasets: a pixel's site, starting with https://.
integrationIds- A new dataset's pixels and CAPI integrations, by their integration ID.
name- The event's name (up to 255 characters).
retargeting- People who did it can be reached again with a tailored audience.
type- The platform's kind of event, such as PURCHASE, SIGN_UP, ADD_TO_CART, SITE_VISIT or CUSTOM.
viewWindow- Days after a view a conversion counts: 0, 1, 7, 14 or 30 (0: views don't count).
Response
adAccountId- The ad account.
donecreated,changedordeleted.id- The conversion event's ID on the platform.
platform- The platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 409The platform's connection can't be used now, the connected account can't manage the ad account, or the platform refused the event (its reason).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversions" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f5f5639c-9386-49de-aee9-aa9deef155a3" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"advancedMatching": true,
"advancedMatchingFields": [
"EMAIL"
],
"clickWindow": 3,
"datasetId": "a1b0ded9-87ad-4039-89d9-7968b9aa5195",
"domain": "brevanne.myshopify.com",
"integrationIds": [
"186642bd-6757-4400-892b-6ee24b45df4f"
],
"name": "vitamin-c-serum-ugc-9x16.mp4",
"retargeting": true,
"type": "video",
"viewWindow": 3
}'Change a conversion event
Changes what the body names of a conversion event in the ad account, on a platform whose conversion events are changed from here. The answer names IDs only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The conversion's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
clickWindow- Days after a click a conversion counts: 1, 7, 14 or 30.
domain- Where conversions are measured with datasets: a pixel's new site.
name- The event's name (up to 255 characters).
retargeting- People who did it can be reached again with a tailored audience.
type- The platform's kind of event.
viewWindow- Days after a view a conversion counts: 0, 1, 7, 14 or 30.
Response
adAccountId- The ad account.
donecreated,changedordeleted.id- The conversion event's ID on the platform.
platform- The platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account or conversion event, or its platform is off for your organization.
- 409The platform's connection can't be used now, the connected account can't manage the ad account, or the platform refused the change (its reason).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversions/358ba268-d087-4ccc-ac23-17f454aa1cf5" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 9bfa5228-4d42-42e6-8da4-1dcbcccb1b7a" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"clickWindow": 3,
"domain": "brevanne.myshopify.com",
"name": "vitamin-c-serum-ugc-9x16.mp4",
"retargeting": true,
"type": "video",
"viewWindow": 3
}'Delete a conversion event
Deletes a conversion event of the ad account for good, on a platform whose conversion events are deleted from here: the platform can't bring it back, and ad sets that optimize for it keep their goal at the platform. The answer names IDs only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The conversion's ID. |
adAccountId | string | Optional | The ad account. |
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
adAccountId- The ad account.
donecreated,changedordeleted.id- The conversion event's ID on the platform.
platform- The platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account or conversion event, or its platform is off for your organization.
- 409The platform's connection can't be used now, the connected account can't manage the ad account, or the platform refused (its reason).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversions/358ba268-d087-4ccc-ac23-17f454aa1cf5" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 7146a614-829c-4869-a261-21d120145cf8"Import campaigns
Each picked campaign of the ad account becomes a launch linked to its live objects, read from the platform: status, budgets, pending changes and history then work like a launch Pluto published. Only the imported ads' images and videos are copied into the media library (deduplicated); what a launch can't hold stays on the platform, with why in the report. dryRun: true answers the review (200) without changing anything: each campaign with what it brings along and whether a launch already manages it. Importing a campaign a launch already manages refreshes that launch (refresh: new ad sets and ads, and willChange, the changes made in Pluto it would put back). For Meta the same as POST /integrations/meta/imports (adSetIds too).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
adSetIds- Meta only.
campaignIds- Each becomes one launch.
dryRun- Only review.
replaceChanges- A refresh puts the launch's changes made in Pluto (the review's
refresh.willChange) back to the platform's values; without it such a refresh answers 409.
Response
jobId and the picked items; with dryRun, 200 with items and notes.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 409A refresh would replace changes made in Pluto: review, then send
replaceChanges. - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/imports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: da8dfcb8-f8eb-44e0-9a26-30490ab0b75d" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"adSetIds": [
"120240541407845332"
],
"campaignIds": [
"120227168091908311"
],
"dryRun": false,
"replaceChanges": true
}'Get an import report
Per campaign: its launch, how many ad sets and ads came along, the media copied, and what stayed on the platform with why.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The import's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
jobId, status and items (each campaign's report).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0" \
-H "Authorization: Bearer $PLUTO_KEY"Get keyword competition
How the ad account competes for its searches, from Pluto's copy of the platform's reports: per campaign (campaigns) and per keyword (keywords) for the period, impression share, top and absolute top impression share, the share lost to rank (lostToRank) and to budget (lostToBudget, a campaign figure; per keyword lostTopToBudget and lostAbsoluteTopToBudget), click share, exact match share, top and absolute top rates and missedImpressions by why; per keyword the cost per click spread (averageCpc, effectiveMaxCpc, and the platform's first page, top of page and first position estimates). Shares are decimals (0.4321), a period's its own numerator over its own denominator, both summed over the days (impressions over eligible impressions, clicks over eligible clicks); bounds names those the platform reports only as under 10% or over 90% (under, over), and a period's share that took in such a day as a bound itself (atMost, atLeast); limitedBy is budget, rank, budget_and_rank or null at 10 points lost. auctionInsights says whether competitors' domains are available. Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Required. The ad account. |
campaignId | string | Optional | Only this campaign's, by its ID at the platform. |
adGroupId | string | Optional | Only this ad set's (ad group's), by its ID at the platform. |
q | string | Optional | Text the keyword or search term contains. |
since | string | Optional | The period's first day (2026-10-01), in the ad account's time zone; with until. Default: the last 30 days. |
until | string | Optional | The period's last day. |
sort | string | Optional | cost (default), clicks, impressions, conversions or text. |
limit | string | Optional | Rows in the answer: 1 to 10000, default 500. |
offset | string | Optional | Rows to skip. |
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
campaigns, keywords, auctionInsights, currency, period, total, truncated.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account, or the platform has no keywords.
- 422A parameter can't be read, or the platform has no keywords.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/keyword-competition" \
-H "Authorization: Bearer $PLUTO_KEY"Forecast keywords
What a set of keywords would bring over a future period (default: next week), as the platform forecasts it for a bid strategy: MANUAL_CPC with maxCpc (and dailyBudget), MAXIMIZE_CLICKS with dailyBudget (and a maxCpc ceiling), or MAXIMIZE_CONVERSIONS with dailyBudget. The platform forecasts cost always, clicks and average CPC for the first two, conversions and cost per conversion for the third; what it doesn't forecast is null. Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
biddingstrategy,maxCpc,dailyBudget, decimals in the ad account's currency.devices- The devices to estimate for, where the platform's planner takes them; every device when left out.
keywords- Up to 10,000.
languages- Languages.
locations- Any number, as the platform takes them; some need at least one.
negativeKeywords- Searches to leave out, where the platform's planner estimates with negatives; refused on this field elsewhere.
periodsinceanduntil: starting tomorrow at the earliest, ending within a year.
Response
forecast (clicks, cost, averageCpc, conversions, averageCpa), strategy, currency.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, or refused the request.
- 422The request doesn't fit, on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/keyword-forecasts" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"bidding": {},
"devices": [
"Computers"
],
"keywords": [
{}
],
"languages": [
"en"
],
"locations": [
"Brevanne"
],
"negativeKeywords": [
{}
],
"period": {}
}'Get keyword ideas
Keyword ideas from the platform's own keyword planner: start from up to 20 keywords, a page's url, both, or a whole site; narrow to locations (as many as the platform's keyword planner takes; it refuses more) and one language (the platform's IDs, from GET /platforms/{platform}/targeting). Each idea has its average monthly searches, competition (and its 0 to 100 index), the low and high top of page bid, monthly volumes for the months asked (months: {from: "2025-11", to: "2026-10"} or historyMonths: 48, up to 4 years back), trend (year over year, the last month against a year before, the last 3 months against the 3 before, direction, the highest month, peak and low calendar months, and a seasonality index per calendar month) and inAccount when the ad account already has it as a keyword. Research runs as the ad account, so it needs one connected. Pages with pageToken. Answers are kept for a day per account and request. Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account whose planner to ask.
averageCpc- The average CPC seen too.
historyMonths- The last 1 to 48 whole months, in place of
months. includeAdult- Adult ideas too.
keywords- Up to 20 keywords to start from.
language- A language ID.
locations- As many as the platform's keyword planner takes; some need at least one.
monthsfromandto, like2026-03.network- Where searches are counted; default with partners.One of
GOOGLE_SEARCH,GOOGLE_SEARCH_AND_PARTNERS pageSize- Ideas per page: 1 to 10000, default 500.
pageToken- The previous page's
nextPageToken. site- A whole website's domain to start from, alone.
url- A page of the website to start from.
Response
items (the ideas), total, nextPageToken, currency and source.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, or refused the request (its reason in
title). - 422The request doesn't fit, on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/keyword-ideas" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"averageCpc": true,
"historyMonths": 3,
"includeAdult": true,
"keywords": [
"Brevanne"
],
"language": "en",
"locations": [
"Brevanne"
],
"months": {},
"network": "GOOGLE_SEARCH",
"pageSize": 18432000,
"pageToken": "HPzf5a7EQAexKVSiRlhzIZI29pBeEJVHFEoXVzow",
"site": "Brevanne",
"url": "https://brevanne.com/products/vitamin-c-serum"
}'Get keyword metrics
The keyword planner's numbers for keywords you name (up to 10,000): the same as each idea of POST /platforms/{platform}/keyword-ideas, trend included, over months or the last historyMonths (up to 48). set is the keywords together: each month's searches summed (monthly) and the set's trend, read over the months every keyword has a number for. Kept for a day. Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
historyMonths- The last 1 to 48 whole months, in place of
months. keywords- The keywords.
language- A language ID.
locations- As many as the platform's keyword planner takes; some need at least one.
monthsfromandto, like2022-11.network- Where searches are counted.One of
GOOGLE_SEARCH,GOOGLE_SEARCH_AND_PARTNERS
Response
items (each with trend), set (monthly, trend), currency and source.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, or refused the request.
- 422The request doesn't fit, on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/keyword-ideas/metrics" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"historyMonths": 3,
"keywords": [
"Brevanne"
],
"language": "en",
"locations": [
"Brevanne"
],
"months": {},
"network": "GOOGLE_SEARCH"
}'List keywords
Every search keyword of the ad account's campaigns, whoever made them: its text, match type, status, its own max CPC and the bid in use, its final URL, what the platform says of it (quality score, review, serving status, first page, first position and top of page bid estimates) and its numbers for the period (clicks, cost, impressions, conversions, CTR, average CPC, conversion value, cost per conversion), with its ad set, campaign and, when a launch manages it, launchId. removed=true lists removed keywords too. A keyword's id is what changes name it by. Where the platform's terms keep its data inside Pluto's own app, outside it each keyword answers its IDs and launchId, with the rest null and withheld: true.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Required. The ad account. |
campaignId | string | Optional | Only this campaign's, by its ID at the platform. |
adGroupId | string | Optional | Only this ad set's (ad group's), by its ID at the platform. |
q | string | Optional | Text the keyword or search term contains. |
since | string | Optional | The period's first day (2026-10-01), in the ad account's time zone; with until. Default: the last 30 days. |
until | string | Optional | The period's last day. |
sort | string | Optional | cost (default), clicks, impressions, conversions or text. |
limit | string | Optional | Rows in the answer: 1 to 10000, default 500. |
offset | string | Optional | Rows to skip. |
format | string | Optional | csv downloads every row (up to 50,000) with every column, the platform's column names first. |
removed | string | Optional | true lists removed keywords too. |
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.
currency- The ad account's currency: every amount is in it, never converted.
items- The keywords, highest cost first by default.
platform- The platform.
readOnlyReason- Why nothing can be changed in this ad account, when that's so;
nullotherwise. total- How many rows the list has in all.
truncated- More rows exist than this answer holds: page with
offset.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account, or the platform has no keywords.
- 422A parameter can't be read, or the platform has no keywords.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/keywords" \
-H "Authorization: Bearer $PLUTO_KEY"Change keywords
Adds, changes and removes keywords at the platform, many at once: {action: "add", adGroupId, text, matchType?, status?, maxCpc?, finalUrl?, exemptPolicies?}, {action: "update", keywordId, status?, maxCpc?, finalUrl?} (null clears the keyword's own bid or final URL), {action: "remove", keywordId} and {action: "changeMatchType", keywordId, matchType} (the platform fixes a keyword's match type, so it's made again with its status, bid and URL, and the old one removed, in one request). Each change is checked first, by Pluto and by the platform itself without changing anything: what doesn't fit answers 422 on its change (changes/3/text); a policy finding the platform reviews on request is named changes/3/exemptPolicies/{topic}, and sending the change again with that topic in exemptPolicies asks for the review. Then the changes run as one job, one all-or-nothing request per campaign. A launch that manages the ad set follows the change. Pausing and enabling needs delivery:write, a bid budgets:write, everything else ads:publish. On a platform whose keyword changes go per ad group, the changes are {action: "add", adGroupId, text, matchType?, status?, bid?} and {action: "update", adGroupId, keywordId, status?, bid?} (match types Exact, Phrase, Broad; statuses Active, Paused; bid a decimal in the account's currency, inside the platform's range for it), a keyword the ad group already has is left as it is, and the job sends one request per ad group, what the platform refuses failing that ad group's request in its words.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
changes- One or more changes.
Response
batches- How many requests go to the platform: one per campaign (one per ad group where changes go per ad group).
changes- How many changes the request held.
jobId- The job; follow it with GET /jobs/{id} and its items with GET /jobs/{id}/items.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, the role on the ad account only reads, or changes through API keys wait for the platform's approval.
- 422A change doesn't fit, each problem on its change.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/keywords" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5cee3f40-a028-4a3f-a9e7-ff2d103ab27d" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"changes": [
{}
]
}'Get minimum budget
The smallest daily budget the ad account takes, read from the platform now, in the account's currency. On a platform whose ad sets hold the budget it is per ad set, so a campaign budget needs at least this for each of its ad sets; where the campaign holds it, per campaign, and campaignType says for which kind. daily is null when the platform gives none. A platform whose floors follow the account's currency in its own table answers the campaign's daily minimum and its bid range (bidMinimum, bidMaximum), never read from the platform; where its terms keep its data inside Pluto's own app, outside it all of them are null with withheld. Check a budget against it before setting one.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account, as GET /platforms/{platform}/… and the integration name it. |
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.
bidMaximum- On a platform that keeps one table of minimums: the largest bid in the currency; null when none, or where
withheld. bidMinimum- On a platform that keeps one table of minimums: the smallest bid.
campaignSpendCap- On a platform that keeps one table of minimums: the smallest campaign spend cap.
campaignType- Where the campaign holds the budget: the kind of campaign the minimum is for, in the platform's words.
currency- The ad account's currency (ISO 4217).
daily- The minimum daily budget, a decimal string in
currency; null when the platform gives none. note- Where the currency shows, when it's withheld.
withheld- The platform's terms keep what is read from it inside Pluto's own app: the currency is left out here.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use, or one that gives no minimum to read, answers404. - 409The platform's connection can't be used now (reconnect it).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/minimum-budget" \
-H "Authorization: Bearer $PLUTO_KEY"List negative keyword lists
The ad account's shared negative keyword lists, each with how many keywords it holds and the campaigns using it. Their keywords are in GET /platforms/{platform}/negative-keywords at level list. Where the platform's terms keep its data inside Pluto's own app, outside it a list's name is null with withheld: true.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Required. The ad account. |
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.
currency- The ad account's currency: every amount is in it, never converted.
items- The lists.
platform- The platform.
readOnlyReason- Why nothing can be changed in this ad account, when that's so;
nullotherwise. total- How many rows the list has in all.
truncated- More rows exist than this answer holds: page with
offset.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account.
- 422The platform has no keywords.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/negative-keyword-lists" \
-H "Authorization: Bearer $PLUTO_KEY"Change negative keyword lists
Makes, renames and removes shared negative keyword lists and chooses the campaigns using them: {action: "create", name, keywords?: [{text, matchType}], campaignIds?}, {action: "rename", listId, name}, {action: "remove", listId}, {action: "attach" | "detach", listId, campaignIds}. Every list change of a request is one all-or-nothing request to the platform.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
changes- The changes.
Response
batches- How many all-or-nothing requests go to the platform.
changes- How many changes the request held.
jobId- The job; follow it with GET /jobs/{id} and its items with GET /jobs/{id}/items.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, the role on the ad account only reads, or changes through API keys wait for the platform's approval.
- 422A change doesn't fit, each problem on its change.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/negative-keyword-lists" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 6aab9650-b256-44c8-a39d-9cd14eff0703" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"changes": [
{}
]
}'List negative keywords
The ad account's negative keywords at every level: on an ad set (ad_group), on a campaign, in a shared list (list), and on the ad account's own list (account), each with what it's added to and the ID removing it takes. limits has how many each level holds. Where the platform's terms keep its data inside Pluto's own app, outside it each negative keyword answers its IDs and level, with its text and match type null and withheld: true.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Required. The ad account. |
campaignId | string | Optional | Only this campaign's (its own and its ad sets'). |
adGroupId | string | Optional | Only this ad set's. |
q | string | Optional | Text the negative keyword contains. |
format | string | Optional | csv downloads them all. |
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.
currency- The ad account's currency: every amount is in it, never converted.
items- The negative keywords.
platform- The platform.
readOnlyReason- Why nothing can be changed in this ad account, when that's so;
nullotherwise. total- How many rows the list has in all.
truncated- More rows exist than this answer holds: page with
offset.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account.
- 422The platform has no keywords.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/negative-keywords" \
-H "Authorization: Bearer $PLUTO_KEY"Change negative keywords
Adds and removes negative keywords: {action: "add", level, campaignId | adGroupId | listId, text, matchType?} (level is ad_group, campaign, list or account; the ad account's own list is made with its first keyword) and {action: "remove", level, id}. Checked and run as POST /platforms/{platform}/keywords is.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
changes- One or more changes.
Response
batches- How many all-or-nothing requests go to the platform: one per campaign, and one for lists.
changes- How many changes the request held.
jobId- The job; follow it with GET /jobs/{id} and its items with GET /jobs/{id}/items.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, the role on the ad account only reads, or changes through API keys wait for the platform's approval.
- 422A change doesn't fit, each problem on its change.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/negative-keywords" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 2fc70971-8951-4ca6-b4d3-4d94edc70c66" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"changes": [
{}
]
}'Upload conversions
Uploads conversions that happened off the site (a call, a store visit) to the account's offline conversion goals, each by its ad click's click ID, on a platform whose conversion goals are made from Pluto. Every conversion is checked before the platform is asked (problems come back on their fields, conversions.3.clickId); the platform's refusals come back per conversion in refused. A goal takes conversions two hours after it's made, and they show in the platform's reports within six hours. The same request again with the same Idempotency-Key answers the same outcome, and a conversion sent twice counts once.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The account.
conversions- Any number: Pluto sends them 1,000 a call, Microsoft's limit.
conversions[].clickId- The ad click's click ID, as the platform's auto-tagging adds it to the landing page's URL (a GUID's 32 characters). Each conversion has it, a hashed email or a hashed phone.
conversions[].conversionName- The offline conversion goal it counts in, by its name.
conversions[].conversionTime- When it happened, within the last 90 days and after the click: RFC 3339 with its offset, or a local time (
2026-11-13T10:30:00) withtimeZone. conversions[].currency- The value's three-letter currency code; none takes the goal's.
conversions[].hashedEmail- Enhanced conversions: the SHA-256 hash of the customer's email address, 64 hexadecimal characters.
conversions[].hashedPhone- Enhanced conversions: the SHA-256 hash of the customer's phone number in E.164 form, 64 hexadecimal characters.
conversions[].timeZone- A time zone name from the platform's list that a local
conversionTimeis in, with its daylight saving time. conversions[].value- What it was worth, a decimal; none takes the goal's value.
Response
accepted- How many conversions the platform took.
adAccountId- The account.
platform- The platform.
refused- The conversions the platform didn't take, by their place in
conversions. refused[].index- The conversion's place in
conversions, from 0. refused[].reason- Why: an unknown click ID, no such offline conversion goal, a goal made less than two hours ago, a time outside the last 90 days, a conversion outside the goal's conversion window, one before its click, the value, the currency, offline conversions not on for the customer, not sent (a failure stopped the upload first), or refused otherwise.One of
clickId,goal,goalTooNew,time,window,beforeClick,value,currency,notEnabled,notSent,refused
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The caller can't publish.
- 404No such page: the platform isn't on for this workspace, or it has no conversion goals or site tags.
- 409The connected user can only view the account, or the connection needs attention.
- 422A value doesn't fit, or the platform refused it, said on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/offline-conversions" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 27a47ba1-9707-46df-9a99-2961c877c433" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"conversions": [
{
"clickId": "fce777db-bda8-4b58-9dbd-c4df01421455",
"conversionName": "Vitamin C Serum, UGC 9x16",
"conversionTime": "2026-09-25T11:00:00Z",
"currency": "USD",
"hashedEmail": "150.00",
"hashedPhone": "150.00",
"timeZone": "2026-09-25T11:00:00Z",
"value": "4210.00"
}
]
}'List portfolios
The ad account's portfolios on a platform that groups campaigns in them, as Pluto last read them from the platform, by name: each portfolio's id (what a launch's campaign takes as its portfolio), name and state. Where the platform's terms keep its data inside Pluto's own app, name and state are null with withheld true on every other channel. Other platforms answer 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. |
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.
data- The portfolios, by name.
data[].id- The portfolio's ID at the platform.
data[].name- Its name; null where
withheld. data[].state- Its state, as the platform writes it; null where
withheld. data[].withheld- The platform's values here are kept in Pluto's own app.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 422No ad account named.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/portfolios" \
-H "Authorization: Bearer $PLUTO_KEY"List the platform's recommendations
Every recommendation the platform makes for the ad account, under the name the platform gives them (source), none left out or reordered: its type and title, its category, the campaign and ad set it's about, the platform's estimated impact (base and potential: impressions, clicks, cost, conversions, conversion value, video views), the figures of its type (facts: a budget, a target, a keyword, in the ad account's currency), the values it can be applied with instead of the platform's (parameters), and the reason the last try didn't go through (lastError). With the account's optimization score and when the list was read. dismissed=true lists the dismissed ones.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Required. The ad account. |
campaignId | string | Optional | Only this campaign's. |
type | string | Optional | Only this type. |
category | string | Optional | bidding_budgets, keywords_targeting, ads_assets, automated_campaigns, measurement, repairs or other. |
dismissed | string | Optional | true lists dismissed recommendations instead. |
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.
currency- The ad account's currency: every amount is in it, never converted.
items- The recommendations.
platform- The platform.
readOnlyReason- Why nothing can be changed in this ad account, when that's so;
nullotherwise. total- How many rows the list has in all.
truncated- More rows exist than this answer holds: page with
offset.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account.
- 422The platform has no recommendations here.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/recommendations" \
-H "Authorization: Bearer $PLUTO_KEY"Apply recommendations
FINANCIAL for recommendations about budgets and bids. Applies recommendations at the platform, each with the platform's own values or the ones you choose where its type takes them (parameters: newBudget, matchType, maxCpc, targetCpa, targetRoas in percent, targetMultiplier, budgetToMove). Takes any number; runs as a job that sends them to the platform 100 a request, each answering for itself: one the platform changed since it was read keeps the reason and the list is read again. Needs budgets:write too for a recommendation that changes what a campaign spends or bids.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
items- At least one; any number.
Response
jobId- The job.
recommendations- How many.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, the role on the ad account only reads, or changes through API keys wait for the platform's approval.
- 422A recommendation is gone, or a value doesn't fit.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/recommendations/apply" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f483c626-2452-431a-b415-3789d6c875e9" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"items": [
{}
]
}'Dismiss recommendations
Dismisses recommendations at the platform: they leave the list (dismissed=true still lists them, and they can be applied later). Takes any number; runs as a job that sends them to the platform 100 a request.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
ids- At least one; any number.
Response
jobId- The job.
recommendations- How many.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, the role on the ad account only reads, or changes through API keys wait for the platform's approval.
- 422A recommendation is gone.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/recommendations/dismiss" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d78d171c-e6f9-464a-a1e7-0985cde2129d" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"ids": [
"1663c055-be5e-43a9-b231-83903ab9bbfa"
]
}'Refresh the platform's recommendations
Reads the ad account's recommendations from the platform now (they're read daily otherwise, and change often) and answers the list.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
Response
The list, as GET /platforms/{platform}/recommendations answers it.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The platform needs reconnecting, or refused the read.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/recommendations/refresh" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437"
}'Get brand search terms
The ad account's search terms for the period classed as brand (the workspace's own), competitor (another brand) or generic: per class its search terms, clicks, impressions, cost, conversions, conversion value, CTR, average CPC, cost per conversion, ROAS and share of cost and conversions, the same for the period before (previous), a weekly trend and its 20 costliest terms; per competitor what its terms cost and brought; and the brand terms used (terms), each with its source (set, workspace_name, ad_domain, brand_list, competitor_research), the account's brand lists and what the workspace set. Matching ignores case, accents, punctuation and spaces and allows one typo. Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Required. The ad account. |
campaignId | string | Optional | Only this campaign's search terms. |
since | string | Optional | The period's first day, in the ad account's time zone; with until. Default: the last 30 days. |
until | string | Optional | The period's last day. |
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
classes, competitors, total, terms, brandLists, set, period, previousPeriod, weeks, currency, truncated.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account, or the platform has no keywords.
- 422A parameter can't be read, or the platform has no keywords.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/search-term-brands" \
-H "Authorization: Bearer $PLUTO_KEY"List search terms
What people searched that showed the ad account's ads, per ad set and match type, with its numbers for the period and its status: ADDED (a keyword of the ad set), EXCLUDED (a negative keyword leaves it out), ADDED_EXCLUDED or NONE, as the platform reports it and as Pluto holds it now (a term added a minute ago reads ADDED). asKeyword is the term as a keyword the platform takes, for POST /platforms/{platform}/keywords and POST /platforms/{platform}/negative-keywords. Where the platform's terms keep its data inside Pluto's own app, a search term is that data: outside it the list holds none, with withheld: true.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | Required. The ad account. |
campaignId | string | Optional | Only this campaign's, by its ID at the platform. |
adGroupId | string | Optional | Only this ad set's (ad group's), by its ID at the platform. |
q | string | Optional | Text the keyword or search term contains. |
since | string | Optional | The period's first day (2026-10-01), in the ad account's time zone; with until. Default: the last 30 days. |
until | string | Optional | The period's last day. |
sort | string | Optional | cost (default), clicks, impressions, conversions or text. |
limit | string | Optional | Rows in the answer: 1 to 10000, default 500. |
offset | string | Optional | Rows to skip. |
format | string | Optional | csv downloads every row (up to 50,000) with every column, the platform's column names first. |
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.
currency- The ad account's currency: every amount is in it, never converted.
items- The search terms.
platform- The platform.
readOnlyReason- Why nothing can be changed in this ad account, when that's so;
nullotherwise. total- How many rows the list has in all.
truncated- More rows exist than this answer holds: page with
offset.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such ad account.
- 422A parameter can't be read, or the platform has no keywords.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/search-terms" \
-H "Authorization: Bearer $PLUTO_KEY"Create a site tag
Creates a site tag (the tag the platform gives the code for, which its conversion goals count through) in the account, on a platform whose site tags are made from Pluto: the code to put on every page of the site then lists with it in GET /platforms/{platform}/conversions. The same request again with the same Idempotency-Key answers the same tag.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The account.
description- What it tracks; empty clears it.
name- Its name, at most 100 characters.
Response
adAccountId- The account.
done- What was done.One of
created,changed id- The goal's or tag's ID at the platform.
platform- The platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The caller can't publish.
- 404No such page: the platform isn't on for this workspace, or it has no conversion goals or site tags.
- 409The connected user can only view the account, or the connection needs attention.
- 422A value doesn't fit, or the platform refused it, said on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/site-tags" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e88e39f9-52f8-4cf5-ace2-66d26c95b41e" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"description": "Two drops every morning for brighter, even skin.",
"name": "Vitamin C Serum, UGC 9x16"
}'Change a site tag
A site tag's new name or description.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The site tag's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The account.
description- What it tracks; empty clears it.
name- Its name, at most 100 characters.
Response
adAccountId- The account.
done- What was done.One of
created,changed id- The goal's or tag's ID at the platform.
platform- The platform.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The caller can't publish.
- 404No such site tag, or no such page for the platform.
- 409The connected user can only view the account, or the connection needs attention.
- 422A value doesn't fit, or the platform refused it, said on its field.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/site-tags/1cd96413-89e3-4a59-b5a6-0e2d7158f18b" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 0b26576f-ee2e-4cb5-8e1f-18665c8643ad" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"description": "Two drops every morning for brighter, even skin.",
"name": "Vitamin C Serum, UGC 9x16"
}'Get a platform's launch settings
The platform's own launch content, for building a launch in its own fields and words: levels and their words, field groups and fields (key, level, group, order, label, kind, option list, required, dependencies), option lists, which objectives allow which formats and bidding, statuses, error copy, previews, text limits and a new launch's defaults. Launches and ad sets take these fields in platformSettings. content is null for a platform whose launch fields are the launch document's own (Meta). The same answer as the get_platform_spec tool.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
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
content- The launch content, or null.
platform- The platform.
version- The spec's version (a date).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/spec" \
-H "Authorization: Bearer $PLUTO_KEY"List store products
A few of a store's products as the platform holds them (each with its image, title and price), on a platform whose Shopping ads show a store's products from its merchant catalog, for the Shopping ad preview; nothing of them is stored. A store the platform doesn't answer for has no items. Where the platform's terms keep its data inside Pluto's own app, items is empty with withheld true on every other channel. Other platforms answer 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
store | string | Required | |
adAccountId | string | Optional | The ad account whose store it is. |
limit | string | Optional | Products, 1-12 (default 4). |
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
storeId and items, or withheld and note.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 409The platform's connection can't be used now (reconnect it).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/stores/0ecbb9d6-2dc4-4046-bdce-d0c0396cbfee/products" \
-H "Authorization: Bearer $PLUTO_KEY"Search a platform's targeting
The platform's targeting values matching q in one facet or kind from the platform's spec, read from the platform now: each value's ID or URN and name, for a launch's or ad set's audience. For Meta, the same answer as GET /integrations/meta/ad-accounts/{id}/targeting-search with type = facet; Meta's facet locations answers countries, regions, cities, postal codes and markets as {kind, key, name, country, region}: a country goes in an ad set's countries by its key, any other item in its places as it is. Meta's facet languages lists every language Meta targets (id is the key an ad set's localeIds takes; q filters by name, empty lists all), audiences the ad account's custom and lookalike audiences (detail custom or lookalike), interestNames names interests by the IDs in q (valid: false for one Meta no longer takes), and customConversions the ad account's custom conversions an ad set can optimize for (eventType the event it counts as, Meta's OTHER too; pixelId its dataset; archived ones left out).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. Searches of the platform's own values (Meta's locations) work without one, with the workspace's connection; an ad account's own lists (Meta's interests) need it. |
facet | string | Optional | The facet or kind, from the platform's spec. |
q | string | Optional | What to look for (1-100 characters). Empty, where the platform suggests: the values the ad account already targets (its synced ad sets and Pluto's draft ones), most used first, each with uses and lastUsedAt, and suggested: true; none when it targets nothing yet. |
limit | string | Optional | Results, 1-100 (default 25). |
locale | string | Optional | The language and country value names come in, like de_DE (default en_US), where the platform names them by locale. |
identity | string | Optional | Who the ads run as, where a facet lists that account's own posts (an existing post an ad promotes). |
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
query and items. A facet that looks accounts up by their handles takes a list of handles or user IDs in q (up to 2,000 characters) and adds refused (each with typed, problem and reason), invalid and tooMany.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404
{platform}is a platform fromGET /platforms(e.g.meta); a platform this workspace can't use answers404. - 409The platform's connection can't be used now (reconnect it).
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/targeting" \
-H "Authorization: Bearer $PLUTO_KEY"List an ad account's platform videos
For a platform whose ads play videos from its own video site: the ad account's videos there that Pluto knows (the media library videos publishing uploaded, once per ad account, and videos added by their link), with where each upload stands, and the ad account's other video assets, read from the platform now. Publishing uploads a launch's videos by itself, as a step of the publish, with the launch's channel, visibility and AI declaration. Another platform answers 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
adAccountId | string | Optional | The ad account. |
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
accountVideos- The ad account's other video assets, read from the platform now.
accountVideos[].assetResourceName- The ad account's video asset.
accountVideos[].title- Its title there.
accountVideos[].youtubeUrl- The video's page.
accountVideos[].youtubeVideoId- The video's ID on the video site.
adAccountId- The ad account.
data- Pluto's videos of the ad account, newest first.
data[].adAccountId- The ad account.
data[].assetResourceName- The ad account's video asset ads use.
data[].byteSize- The file's size, for an upload.
data[].channelId- The brand channel it was uploaded to;
null: the channel the platform manages for the ad account (unlisted only). data[].createdAt- When Pluto added it.
data[].error- Why it failed: the platform's or Pluto's code and the sentence to show.
data[].error.codedata[].error.messagedata[].generativeContent- What the upload declared: whether the video was made or changed with AI.One of
NON_GENERATIVE_CONTENT,GENERATIVE_CONTENT data[].id- Pluto's ID of the video in this ad account.
data[].mediaId- The media library video, for an upload.
data[].privacy- Who can find it on the video site.One of
UNLISTED,PUBLIC data[].removedAt- When Pluto removed it.
data[].sentBytes- The bytes sent so far, while uploading.
data[].sourceupload: a media library video publishing put on the platform's video site.youtube: a video already there, added by its link.One ofupload,youtubedata[].statusreadyonce ads can use it.One ofuploading,processing,ready,faileddata[].title- The title it was uploaded with, or the site's title of a video added by link.
data[].uploadState- The platform's own state of the upload.One of
PENDING,UPLOADED,PROCESSED,FAILED,REJECTED,UNAVAILABLE data[].youtubeUrl- The video's page.
data[].youtubeVideoId- The video's ID on the video site.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The platform has no such list, or no such ad account is connected.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/videos" \
-H "Authorization: Bearer $PLUTO_KEY"Add a video by its link
Adds a video that's already on the platform's video site to an ad account, by its link (a watch, short, share or embed link) or its 11-character ID. The platform checks the video first; one it doesn't have, a private one, or one it can't use in ads is refused with 422 on video, in the platform's words, and nothing is created. Otherwise it becomes a video asset of the ad account (the one the account has, if any). Adding the same video again answers it with 200.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- The ad account.
video- The video's link or ID.
Response
code- Stable code.One of
bad_request,unauthenticated,forbidden,not_found,conflict,invalid,rate_limited,unavailable,internal current- The current entity, on a stale
expectedVersion(409). errors- Every field problem (422).
errors[].code- A registered reason's stable code (such as
ad_account_not_in_meta), so an app can saymessagein its own words; absent for a reason without one. errors[].field- JSON-pointer-like path.
errors[].message- Problem.
errors[].params- The values
code's sentence names (maybe none), present exactly whencodeis. requestId- The request's ID, as in the
x-request-idheader. Include it when you report a problem. status- HTTP status.
title- What went wrong, for the person or agent reading it.
titleCode- A registered
title's stable code (such asnot_found_the_launch), for an app to say the title in its language; absent for a title without one.titlereads the same either way. titleParams- The values
titleCode's sentence names, present exactly whentitleCodeis. traceId- The request's trace ID, as in the
x-trace-idheader. type- Documentation URL for
code.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The platform has no such list, or no such ad account is connected.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Not a link to a video, or the platform refused the video (
video). - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/videos" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 95081044-7731-483f-9087-744f16a1857b" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"video": "vitamin-c-serum-ugc-9x16.mp4"
}'Change a video's visibility
Makes a video Pluto uploaded to the ad account's brand channel public or unlisted, the one thing the platform changes after an upload. A video on the channel the platform manages stays unlisted (422 on privacy).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The video'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
privacy- Who can find it on the video site.One of
UNLISTED,PUBLIC
Response
adAccountId- The ad account.
assetResourceName- The ad account's video asset ads use.
byteSize- The file's size, for an upload.
channelId- The brand channel it was uploaded to;
null: the channel the platform manages for the ad account (unlisted only). createdAt- When Pluto added it.
error- Why it failed: the platform's or Pluto's code and the sentence to show.
error.codeerror.messagegenerativeContent- What the upload declared: whether the video was made or changed with AI.One of
NON_GENERATIVE_CONTENT,GENERATIVE_CONTENT id- Pluto's ID of the video in this ad account.
mediaId- The media library video, for an upload.
privacy- Who can find it on the video site.One of
UNLISTED,PUBLIC removedAt- When Pluto removed it.
sentBytes- The bytes sent so far, while uploading.
sourceupload: a media library video publishing put on the platform's video site.youtube: a video already there, added by its link.One ofupload,youtubestatusreadyonce ads can use it.One ofuploading,processing,ready,failedtitle- The title it was uploaded with, or the site's title of a video added by link.
uploadState- The platform's own state of the upload.One of
PENDING,UPLOADED,PROCESSED,FAILED,REJECTED,UNAVAILABLE youtubeUrl- The video's page.
youtubeVideoId- The video's ID on the video site.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such video.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422The video isn't on a brand channel (
privacy). - 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/videos/4da14563-bf58-4f70-9f84-afc3d5bbb35f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e9ceb17a-fc31-4f48-8c4a-0a138d004a28" \
-H "Content-Type: application/json" \
-d '{
"privacy": "UNLISTED"
}'Remove a video
Removes a video Pluto uploaded from the ad account's assets and from the platform's video site, for good. A video added by its link only leaves Pluto's list: it isn't Pluto's to remove from the video site. A video an ad uses, at the platform or in a launch that's live, is never removed: that answers 409 and nothing changes. A video still uploading answers 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The video'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
adAccountId- The ad account.
assetResourceName- The ad account's video asset ads use.
byteSize- The file's size, for an upload.
channelId- The brand channel it was uploaded to;
null: the channel the platform manages for the ad account (unlisted only). createdAt- When Pluto added it.
error- Why it failed: the platform's or Pluto's code and the sentence to show.
error.codeerror.messagegenerativeContent- What the upload declared: whether the video was made or changed with AI.One of
NON_GENERATIVE_CONTENT,GENERATIVE_CONTENT id- Pluto's ID of the video in this ad account.
mediaId- The media library video, for an upload.
privacy- Who can find it on the video site.One of
UNLISTED,PUBLIC removedAt- When Pluto removed it.
sentBytes- The bytes sent so far, while uploading.
sourceupload: a media library video publishing put on the platform's video site.youtube: a video already there, added by its link.One ofupload,youtubestatusreadyonce ads can use it.One ofuploading,processing,ready,failedtitle- The title it was uploaded with, or the site's title of a video added by link.
uploadState- The platform's own state of the upload.One of
PENDING,UPLOADED,PROCESSED,FAILED,REJECTED,UNAVAILABLE youtubeUrl- The video's page.
youtubeVideoId- The video's ID on the video site.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404No such video.
- 409An ad uses the video, or it's still uploading.
- 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/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/videos/4da14563-bf58-4f70-9f84-afc3d5bbb35f" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a25852e1-a498-41cb-8f98-0370991a012d"Get a platform connection
The workspace's connection to an ad platform from GET /platforms: status and why it needs a person, permissions and products it lacks, when access ends, the last sync, the ad accounts with the connected person's role, and the Pages ads run as. available: false when this deployment can't connect the platform yet. 404 for a platform the workspace can't use. For a caller with views:write whose credential reaches the whole platform, reading it also keeps the data current: when the last sync is older than the platform's window (15 minutes for most, longer where the platform's read budget is daily) and none is waiting, one background sync is queued, paced as the scheduler's own; the answer doesn't wait for it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
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
The connection: platform, available, status (connected, reauthorize, disconnected), statusReason, reason, missingPermissions, products, missingProducts, missingFeatures (LinkedIn: page_posts, audiences; each asks for a reconnect only where it's used), attention (title, message), syncedAt, tokenExpiresAt, accessEndsAt, tokenExpiry, version, lastSync (jobId, status, error, errorCode, errorParams, finishedAt), adAccounts and adAccountsOff (id, name, currency, status, type, test, role, editsCampaigns, editsAds, servingStatuses, reference), pages and pagesOff (id, name, vanityName, roles, sponsors), adAccountLimit. adAccounts are on (synced, counted against the plan's cap, offered everywhere); adAccountsOff are listed by the platform and off (a new one arrives off). pages are on (offered wherever a Page is chosen); pagesOff are offered nowhere and a launch can't publish as them (a new Page arrives off).
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The workspace can't use this platform.
- 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/integrations/59a4cf9d-a07f-4bfd-9d81-e8712666cabf" \
-H "Authorization: Bearer $PLUTO_KEY"Switch an ad account
The platform lists every ad account the person who connected has a role on, and each one arrives off (adAccountsOff in GET /integrations/{platform}): nothing of it is synced, counted against the plan's ad account cap or offered anywhere in Pluto until it's on. On: Pluto starts reading its campaigns, ad sets, ads and insights, and jobId is that sync (null while the platform needs reconnecting: the first sync after it reads the account); past the plan's cap it's a 402 plan_limit and nothing changes. Off: syncing it stops at once and it leaves every list; what it synced (launches, insights, leads) stays, read-only, and turning it on again goes on from there. Setting the state it already has changes nothing. Meta's is PUT /integrations/meta/ad-accounts/{id}/sync. The same command as MCP switch_platform_ad_account.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The ad account'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
enabledtrueturns it on,falseoff.
Response
adAccountId- Account.
enabled- Whether it's on now.
jobId- The sync that brings it in, when this turned it on.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The connection doesn't list this ad account, or the platform has no ad account switch.
- 409The platform isn't connected.
- 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 PUT "$PLUTO_API/integrations/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/ad-accounts/7189f819-3670-4cb3-9d5e-b0f6cb215e8e/sync" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: c2cda89d-8c8e-49ea-bf18-d4aad223d5e4" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'Connect an ad platform
Start connecting an ad platform for a person.
Returns the platform's consent URL for a person to open in their browser; nothing connects until they approve. The URL works once, for 15 minutes. reconnect: true signs in again for an existing connection. Needs a credential that acts for a person (an API key gets 403). 409 when the platform is already connected (connect), isn't (reconnect), or can't be connected in this deployment yet. The same command as MCP connect_platform.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
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
reconnect- Sign in again for an existing connection instead of connecting.
returnTo- Where the app opens after the consent, a path such as
/integrations(the default).
Response
authorizationUrl- The consent page for the person to open in their browser (single use).
expiresAt- The URL stops working after this.
personId- The person who must open the URL, signed in to Pluto Ads.
status- The connection's status before the consent.One of
connected,reauthorize,disconnected
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Already connected, not connected (reconnect), or not available yet.
- 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/integrations/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/connect" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: a312aec8-74fc-4c35-8a46-8fdde89718e9" \
-H "Content-Type: application/json" \
-d '{
"reconnect": true,
"returnTo": "/settings/billing"
}'Disconnect an ad platform
Revokes Pluto Ads' access at the platform when possible, deletes the stored tokens and cancels open syncs. Launches and synced data stay for as long as the platform's terms allow. The same command as MCP disconnect_platform.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
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
The connection: platform, available, status (connected, reauthorize, disconnected), statusReason, reason, missingPermissions, products, missingProducts, missingFeatures (LinkedIn: page_posts, audiences; each asks for a reconnect only where it's used), attention (title, message), syncedAt, tokenExpiresAt, accessEndsAt, tokenExpiry, version, lastSync (jobId, status, error, errorCode, errorParams, finishedAt), adAccounts and adAccountsOff (id, name, currency, status, type, test, role, editsCampaigns, editsAds, servingStatuses, reference), pages and pagesOff (id, name, vanityName, roles, sponsors), adAccountLimit. adAccounts are on (synced, counted against the plan's cap, offered everywhere); adAccountsOff are listed by the platform and off (a new one arrives off). pages are on (offered wherever a Page is chosen); pagesOff are offered nowhere and a launch can't publish as them (a new Page arrives off).
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/integrations/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/disconnect" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 05474409-509d-4229-ab79-41d318ee90f1"Switch a Page
A new Page arrives off (pagesOff in GET /integrations/{platform}) and one already stored keeps its switch. On: offered wherever a Page is chosen (launches, defaults, loops, agents). Off: offered nowhere, so a workspace keeps the list short and never publishes as a Page it doesn't use; a launch whose ad set names it can't publish until another Page is chosen, and an ad already live as it stays as it is. Leads that belong to the ad accounts go on. It moves between pages and pagesOff in GET /integrations/{platform}. Setting the state it already has changes nothing. Meta's is PUT /integrations/meta/pages/{id}/enabled. The same command as MCP switch_platform_page.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The page'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
enabledtrueturns it on,falseoff.
Response
enabled- Whether it's on now.
pageId- Page.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The connection doesn't list this Page, or the platform has no Pages.
- 409The platform isn't connected.
- 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 PUT "$PLUTO_API/integrations/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/pages/65ed0584-aa3e-40e6-a062-786ca33d5821/enabled" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f4926945-0352-41a0-a5a7-3a3fe7e7561e" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'Sync an ad platform
Returns the queued (or already running) sync job: the connection's ad accounts and Pages. A scope (adAccountId, campaignId, adSetId, adId) is refused (422) where the platform doesn't support one. 409 when the platform isn't connected or needs reconnecting. The same command as MCP sync_platform.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- Only this ad account, where supported.
adId- Only this synced ad, where supported.
adSetId- Only this synced ad set, where supported.
campaignId- Only this synced campaign, where supported.
Response
jobId- The sync job.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Not connected, or needs reconnecting.
- 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/integrations/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/sync" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 679a7190-6e59-4a92-9331-cb40e9211139" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"adId": "120288304425086360",
"adSetId": "120240541407845332",
"campaignId": "120227168091908311"
}'