API reference

Ad platforms

The ad platforms you can use, their launch settings and targeting, and the LinkedIn connection, and the X connection.

GET/platforms

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.

Permission: read

Parameters

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

Response200 OK

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

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/account-assets

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
dataarray of objectsRequired
Every callout linked to the ad account.
data[].idstringRequired
The asset's ID at the platform: what removing it names.
data[].primaryStatusstring or nullRequired
Whether it serves, after the platform's review.
data[].statusstring or nullRequired
The link's status, in the platform's words (ENABLED, PAUSED, Active).
data[].textstring or nullRequired
The callout's text; null with withheld where the platform's terms keep it in Pluto's own app.
typestringRequired
callout.

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-After seconds. 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"
POST/platforms/{platform}/account-assets

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
textstringRequired
The callout's text, 1 to 25 characters.
typestring
callout (the default).

Response201 Created

idstringRequired
The asset's ID at the platform: what removing it names.
primaryStatusstring or nullRequired
Whether it serves, after the platform's review.
statusstring or nullRequired
The link's status, in the platform's words (ENABLED, PAUSED, Active).
textstring or nullRequired
The callout's text; null with withheld where 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-After seconds. 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"
  }'
DELETE/platforms/{platform}/account-assets/{id}

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
idstringRequired
The asset.
removedbooleanRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/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/platforms/{platform}/account-settings

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalThe ad account, by its ID at the platform.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accountobject or null
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_CONVERSION or VIEW_THROUGH_CONVERSION), clickAttributionWindow and viewAttributionWindow (DAY, WEEK or MONTH: the windows its reports count conversions in), the app install campaigns' own appAttributionType, appClickAttributionWindow and appViewAttributionWindow, excludedCommunities and excludedKeywords (where and next to what the account's ads never run), spendCapType (LIFETIME when the account has a spend cap), pixelPartners (measurement partners it allows), redditorHighlightsDefault, status, kind (MANAGED or SELF_SERVE) and suspensionReason. 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 (AUCTION or RESERVATION), balance (the total, a decimal string in its currency), createdAt and ownerBusinessCenterId. Null where withheld.
adAccountIdstringRequired
The ad account.
appsarray of objects or null
The mobile apps associated with the ad account, each {id, appStoreIdentifier, osType, conversionTracking}: what an app campaign's ad group promotes. Null where withheld.
audiencesarray of objects or null
Its audiences, each {id, name, sourceType, size, targetableStatus}. Null where withheld.
billingobject or null
The ad account's billing as the platform holds it: billingType (IO or REVOLVING), spendCap (its lifetime spend cap in its currency, a decimal string, or null), advertiser, agency and fundingSourceIds. Null where withheld.
contactobject or null
The connected user's contact settings on the ad account: notificationEmail, contactPhone, contactPhoneExtension. Null where withheld.
fundingInstrumentsarray of objects or null
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 (fundingInstrumentsReason says why) and where withheld.
fundingInstrumentsReasonstring or null
Why fundingInstruments is null when the platform refused it: only an admin of the ad account may read them.
fundingSourcesarray of objects or null
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 (fundingSourcesReason says why) and where withheld.
fundingSourcesReasonstring or null
Why fundingSources is null when the platform refused it: only an organization's admin may read them.
pixelsarray of objects or null
The pixels and apps it counts conversions with, each {id, name, kind, status} (kind is pixel or the platform's own word for an app). Null where withheld.
taxobject or null
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 (taxReason says why) and where withheld.
taxReasonstring or null
Why tax is null when the platform refused it: only the ad account's administrator may read it.
withheldbooleanRequired
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-After seconds. 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"
PATCH/platforms/{platform}/account-settings

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account, by its ID at the platform.
addressstring
The business address its receipts show.
appAttributionTypestring
The app install campaigns' own type.One of ALL_CONVERSION, CLICK_THROUGH_CONVERSION, VIEW_THROUGH_CONVERSION
appClickAttributionWindowstring
The app install campaigns' own click window.One of DAY, WEEK, MONTH
appViewAttributionWindowstring
The app install campaigns' own view window.One of DAY, WEEK, MONTH
attributionTypestring
Which conversions its reports count: clicks and views, clicks or views.One of ALL_CONVERSION, CLICK_THROUGH_CONVERSION, VIEW_THROUGH_CONVERSION
clickAttributionWindowstring
How long after a click a conversion counts.One of DAY, WEEK, MONTH
companystring
Its company name, where the platform lets its API change it (companyEditable).
contactEmailstring
Its contact's email.
contactNamestring
Its contact person.
contactNumberstring
Its contact's phone number.
excludedCommunitiesarray of strings
The communities (by name, r/ optional) where its ads never run: the whole list, empty to clear it.
excludedKeywordsarray of strings
Keywords that keep its ads out of an auction: the whole list, empty to clear it.
namestring
The ad account's own name, where the platform keeps its profile.
redditorHighlightsDefaultboolean or null
Whether new eligible ads start with creator highlights on; null for the platform's default.
viewAttributionWindowstring
How long after a view a conversion counts.One of DAY, WEEK, MONTH

Response200 OK

accountobject or null
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_CONVERSION or VIEW_THROUGH_CONVERSION), clickAttributionWindow and viewAttributionWindow (DAY, WEEK or MONTH: the windows its reports count conversions in), the app install campaigns' own appAttributionType, appClickAttributionWindow and appViewAttributionWindow, excludedCommunities and excludedKeywords (where and next to what the account's ads never run), spendCapType (LIFETIME when the account has a spend cap), pixelPartners (measurement partners it allows), redditorHighlightsDefault, status, kind (MANAGED or SELF_SERVE) and suspensionReason. 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 (AUCTION or RESERVATION), balance (the total, a decimal string in its currency), createdAt and ownerBusinessCenterId. Null where withheld.
adAccountIdstringRequired
The ad account.
fundingInstrumentsarray of objects or null
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 (fundingInstrumentsReason says why) and where withheld.
fundingInstrumentsReasonstring or null
Why fundingInstruments is null when the platform refused it: only an admin of the ad account may read them.
withheldbooleanRequired
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-After seconds. 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"
  }'
GET/platforms/{platform}/ad-previews

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adIdquerystringOptionalAn ad, by its Pluto ID or its ID on the platform; repeatable or comma-separated (1-25).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

notFoundarray of stringsRequired
IDs that name no published ad of the workspace's on the platform.
notestring
Where the previews show, when they're withheld.
platformstringRequired
The platform asked.
previewsarray of objectsRequired
One per ad found.
previews[].adAccountIdstringRequired
The ad account.
previews[].adIdstring (uuid) or null
The Pluto ad, when a launch made or imported it.
previews[].expiresAtstring
When the platform's addresses stop working, as the platform writes it; ask again after.
previews[].htmlstring or nullRequired
The frame's markup as the platform answered it; null as url.
previews[].opensstringRequired
How url opens: 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 of frame, page
previews[].platformAdIdstringRequired
The ad's ID on the platform.
previews[].postIdstringRequired
What the preview shows, by its ID on the platform (the promoted post, the asset group or ad previewed).
previews[].previewTypestring
The kind of preview the platform made, in its own words, where it makes more than one.
previews[].tvUrlstring or null
The ad on a TV, where the platform renders that too; null as url.
previews[].urlstring or nullRequired
The address of the frame the platform renders the preview in; null where withheld or when the platform answered none.
previews[].withheldbooleanRequired
The platform's terms keep what is read from it inside Pluto's own app (policy.dataLeavesUi off on GET /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-After seconds. 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"
GET/platforms/{platform}/ad-sets

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalOnly this ad account.
statusquerystringOptionalOnly this status, as the platform reports it (e.g. ACTIVE or PAUSED).
searchquerystringOptionalPart of the name, or the exact ID.
afterquerystringOptionalCursor: nextAfter from the previous page.
limitquerystringOptionalPage size, 1-500 (default 200).
campaignIdquerystringOptionalOnly this campaign's ad sets.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

dataarray of objectsRequired
This page.
nextAfterstring or nullRequired
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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/ad-sets" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/ads

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalOnly this ad account.
statusquerystringOptionalOnly this status, as the platform reports it (e.g. ACTIVE or PAUSED).
searchquerystringOptionalPart of the name, or the exact ID.
afterquerystringOptionalCursor: nextAfter from the previous page.
limitquerystringOptionalPage size, 1-500 (default 200).
campaignIdquerystringOptionalOnly this campaign's ads.
adSetIdquerystringOptionalOnly this ad set's ads.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

dataarray of objectsRequired
This page.
nextAfterstring or nullRequired
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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/ads" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/platforms/{platform}/audience-estimate

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.

Permission: read

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
adSetobject
With campaign: the ad group's settings (platformSettings.adSet with its own keys); audience replaces its targeting. A bid strategy that sets a bid also answers the suggested bids (bid).
audienceobjectRequired
The audience, as an ad set's settings hold it on the platform (audience in its spec).
campaignobject
Where the platform forecasts a whole ad group: the campaign's settings (platformSettings.campaign), so the forecast follows its objective and budget. 422 on a platform that estimates the audience alone.
identitystring
The identity the ads run as, where an audience of its followers needs it.

Response200 OK

adAccountIdstringRequired
The ad account.
bidobject or null
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.
currencystring
The ad account's currency, where delivery or plan carry amounts.
deliveryobject or null
Where the platform also forecasts delivery: a week's ranges (impressions, clicks, conversions, reach, videoViews, installs, each {min, max}) and totalAudienceSize; null where withheld.
estimablebooleanRequired
Whether the platform estimates this audience: on some platforms an audience made only of locations, age, gender, language and devices has no estimate.
maxinteger or nullRequired
The most people; null as min.
mininteger or nullRequired
The fewest people the platform expects the audience to reach; null when it can't be estimated, or where withheld.
notestring
Where the estimate shows, when it's withheld.
planobject or null
Where the platform also forecasts a plan: its reach curve per budget and what the plan's own budget projects; null where withheld.
withheldbooleanRequired
The platform's terms keep what is read from it inside Pluto's own app (policy.dataLeavesUi off on GET /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-After seconds. 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"
  }'
GET/platforms/{platform}/audiences

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
doNotReachobject or nullRequired
The ad account's do-not-reach list, when it has one: its people never see the account's ads.
doNotReach.actionsarray of strings
What can be done to it here, where the platform says per audience (replaceList: PUT …/{id}/members; createLookalike: POST …/audiences/lookalikes); left out where editable says it all, and outside Pluto's own app where the platform's terms keep its data there.
doNotReach.descriptionstring or null
Its description, when it has one.
doNotReach.editableboolean or null
Whether people can be added and taken out here, and it renamed and deleted (the ad account's own list).
doNotReach.idstringRequired
The audience at the platform: what an ad set's audience takes.
doNotReach.kindstring or nullRequired
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 of customers, companies, doNotReach, website, app, lookalike, combined, product, other
doNotReach.namestring or nullRequired
Its name; null where withheld.
doNotReach.reasonsarray of strings or null
The platform's reasons when it can't be targeted (PROCESSING, TOO_SMALL).
doNotReach.sizeinteger or nullRequired
How many people the platform matched; null while it's matching, below its minimum, or where withheld.
doNotReach.usableboolean or nullRequired
Whether an ad set may target it now; null where withheld.
doNotReach.withheldbooleanRequired
The platform's terms keep what is read from it inside Pluto's own app (policy.dataLeavesUi off on GET /platforms): its values here are null. Everywhere but Pluto's own app.
itemsarray of objectsRequired
Its audiences, newest first.
items[].actionsarray of strings
What can be done to it here, where the platform says per audience (replaceList: PUT …/{id}/members; createLookalike: POST …/audiences/lookalikes); left out where editable says it all, and outside Pluto's own app where the platform's terms keep its data there.
items[].descriptionstring or null
Its description, when it has one.
items[].editableboolean or null
Whether people can be added and taken out here, and it renamed and deleted (the ad account's own list).
items[].idstringRequired
The audience at the platform: what an ad set's audience takes.
items[].kindstring or nullRequired
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 of customers, companies, doNotReach, website, app, lookalike, combined, product, other
items[].namestring or nullRequired
Its name; null where withheld.
items[].reasonsarray of strings or null
The platform's reasons when it can't be targeted (PROCESSING, TOO_SMALL).
items[].sizeinteger or nullRequired
How many people the platform matched; null while it's matching, below its minimum, or where withheld.
items[].usableboolean or nullRequired
Whether an ad set may target it now; null where withheld.
items[].withheldbooleanRequired
The platform's terms keep what is read from it inside Pluto's own app (policy.dataLeavesUi off on GET /platforms): its values here are null. Everywhere but Pluto's own app.
minMatchedintegerRequired
People an audience must match before an ad set may target it.
notestring
Where the platform's values show, when they're withheld.
platformstringRequired
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-After seconds. 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"
POST/platforms/{platform}/audiences

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

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
adSetIdsarray of strings
For kind: engagement: the ad sets whose ads people saw or clicked.
campaignIdsarray of strings
For kind: engagement: the ad account's campaigns whose ads people saw or clicked, by their ID on the platform.
companiesarray of objects
For a company list (kind: companies, where the platform makes them): the companies, each with a name, website, email domain or page address.
companies[].countrystring
A two-letter country code, helping the match.
companies[].emailDomainstring
The domain its people's emails use.
companies[].namestring
The company's name.
companies[].pageUrlstring
Its company page address on the platform.
companies[].websitestring
Its website (example.com).
customEventsarray of strings
For kind: website with CUSTOM among events: the custom events' names.
datasetIdsarray of strings
For kind: website: the datasets whose events count.
definitionobject
For an audience the platform fills itself (kind website, combined or product, where it makes them): how it's defined; on a change only what it names changes.
definition.combinationRulesarray of objects
A combined audience's combinations, in the platform's own shape (the audiences and how they combine), as detail.combinationRules shows them; replaced whole.
definition.membershipDurationinteger
Days people stay in it (website and product audiences).
definition.productAudienceTypestring
Who a product audience reaches, in the platform's words.
definition.ruleobject
A website audience's rule, in the platform's own shape (its Type and conditions), as detail.rule shows it; replaced whole.
definition.tagIdstring
The site tag that collects the people (website and product audiences).
descriptionstring
A description (up to 1,000 characters), where the platform keeps one.
engagementsarray of strings
For kind: engagement: what people did with the ads (IMPRESSIONS, CLICKS, UPVOTES, COMMENT_SUBMISSIONS, VIDEO_STARTED, VIDEO_WATCHED_50_PERCENT, VIDEO_WATCHED_100_PERCENT).
eventsarray of strings
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).
excludedEventsarray of strings
For kind: website: events whose people are left out.
exposureTypestring
For kind: engagement: saw the ads (default) or clicked them.One of IMPRESSIONS, CLICKS
includedEventsarray of strings
For kind: website: the events people did.
kindstring
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 a definition where it makes them (website, combined, product).One of customers, companies, doNotReach, website, engagement, combined, product
linesarray of strings
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.
lookbackDaysinteger
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).
namestring
The customer list's name, unique in the ad account (up to 255 characters).
peoplearray of objects
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[].companystring
The company the person works at, helping a name match.
people[].countrystring
A two-letter country code, helping a name match.
people[].deviceIdstring
A mobile advertising ID (IDFA, AdID) or Android ID.
people[].emailstring
An email address.
people[].firstNamestring
A first name, where the platform matches people by name (with lastName).
people[].handlestring
A username on the platform, with or without @.
people[].lastNamestring
A last name, with firstName.
people[].phonestring
A phone number with its country code (+45 25 73 66 00).
people[].titlestring
A job title, helping a name match.
people[].xUserIdstring
A user ID on the platform (digits).
pixelIdstring
For kind: website: the pixel whose events make the audience (from list_platform_conversions).

Response201 Created

acceptedinteger
Rows the platform took, where it answers row by row; absent where it doesn't say.
actionstringRequired
What was done (replaced: the list's people replaced whole, where the platform takes a list whole).One of created, added, removed, replaced, updated, deleted
adAccountIdstringRequired
The ad account.
audienceIdstringRequired
The audience at the platform.
givenintegerRequired
People the request named.
kindstringRequired
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
namestring or nullRequired
The name the request gave, when it gave one.
notestringRequired
What happens next.
sentintegerRequired
People sent to the platform (each with at least one value it can match).
skippedintegerRequired
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-After seconds. 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"
  }'
POST/platforms/{platform}/audiences/lookalikes

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
countriesarray of strings
Where the platform takes them: the countries it finds people in.
descriptionstring
A description, where the platform keeps one.
namestringRequired
The look-alike's name.
sizeinteger
Where the platform takes one: how close a match, as the platform counts it.
sourceAudienceIdstringRequired
The audience to find people like.

Response201 Created

acceptedinteger
Rows the platform took, where it answers row by row; absent where it doesn't say.
actionstringRequired
What was done (replaced: the list's people replaced whole, where the platform takes a list whole).One of created, added, removed, replaced, updated, deleted
adAccountIdstringRequired
The ad account.
audienceIdstringRequired
The audience at the platform.
givenintegerRequired
People the request named.
kindstringRequired
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
namestring or nullRequired
The name the request gave, when it gave one.
notestringRequired
What happens next.
sentintegerRequired
People sent to the platform (each with at least one value it can match).
skippedintegerRequired
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-After seconds. 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"
  }'
PATCH/platforms/{platform}/audiences/{id}

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
definitionobject
For an audience the platform fills itself (kind website, combined or product, where it makes them): how it's defined; on a change only what it names changes.
definition.combinationRulesarray of objects
A combined audience's combinations, in the platform's own shape (the audiences and how they combine), as detail.combinationRules shows them; replaced whole.
definition.membershipDurationinteger
Days people stay in it (website and product audiences).
definition.productAudienceTypestring
Who a product audience reaches, in the platform's words.
definition.ruleobject
A website audience's rule, in the platform's own shape (its Type and conditions), as detail.rule shows it; replaced whole.
definition.tagIdstring
The site tag that collects the people (website and product audiences).
descriptionstring
The new description; empty clears it.
namestring
The new name (up to 255 characters).

Response200 OK

acceptedinteger
Rows the platform took, where it answers row by row; absent where it doesn't say.
actionstringRequired
What was done (replaced: the list's people replaced whole, where the platform takes a list whole).One of created, added, removed, replaced, updated, deleted
adAccountIdstringRequired
The ad account.
audienceIdstringRequired
The audience at the platform.
givenintegerRequired
People the request named.
kindstringRequired
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
namestring or nullRequired
The name the request gave, when it gave one.
notestringRequired
What happens next.
sentintegerRequired
People sent to the platform (each with at least one value it can match).
skippedintegerRequired
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-After seconds. 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/platforms/{platform}/audiences/{id}

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Response200 OK

acceptedinteger
Rows the platform took, where it answers row by row; absent where it doesn't say.
actionstringRequired
What was done (replaced: the list's people replaced whole, where the platform takes a list whole).One of created, added, removed, replaced, updated, deleted
adAccountIdstringRequired
The ad account.
audienceIdstringRequired
The audience at the platform.
givenintegerRequired
People the request named.
kindstringRequired
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
namestring or nullRequired
The name the request gave, when it gave one.
notestringRequired
What happens next.
sentintegerRequired
People sent to the platform (each with at least one value it can match).
skippedintegerRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/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"
POST/platforms/{platform}/audiences/{id}/members

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
companiesarray of objects
For a company list (kind: companies, where the platform makes them): the companies, each with a name, website, email domain or page address.
companies[].countrystring
A two-letter country code, helping the match.
companies[].emailDomainstring
The domain its people's emails use.
companies[].namestring
The company's name.
companies[].pageUrlstring
Its company page address on the platform.
companies[].websitestring
Its website (example.com).
peoplearray of objects
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[].companystring
The company the person works at, helping a name match.
people[].countrystring
A two-letter country code, helping a name match.
people[].deviceIdstring
A mobile advertising ID (IDFA, AdID) or Android ID.
people[].emailstring
An email address.
people[].firstNamestring
A first name, where the platform matches people by name (with lastName).
people[].handlestring
A username on the platform, with or without @.
people[].lastNamestring
A last name, with firstName.
people[].phonestring
A phone number with its country code (+45 25 73 66 00).
people[].titlestring
A job title, helping a name match.
people[].xUserIdstring
A user ID on the platform (digits).
removeboolean
Take these people out instead of adding them.

Response200 OK

acceptedinteger
Rows the platform took, where it answers row by row; absent where it doesn't say.
actionstringRequired
What was done (replaced: the list's people replaced whole, where the platform takes a list whole).One of created, added, removed, replaced, updated, deleted
adAccountIdstringRequired
The ad account.
audienceIdstringRequired
The audience at the platform.
givenintegerRequired
People the request named.
kindstringRequired
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
namestring or nullRequired
The name the request gave, when it gave one.
notestringRequired
What happens next.
sentintegerRequired
People sent to the platform (each with at least one value it can match).
skippedintegerRequired
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-After seconds. 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
  }'
PUT/platforms/{platform}/audiences/{id}/members

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
linesarray of strings
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.
peoplearray of objects
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[].companystring
The company the person works at, helping a name match.
people[].countrystring
A two-letter country code, helping a name match.
people[].deviceIdstring
A mobile advertising ID (IDFA, AdID) or Android ID.
people[].emailstring
An email address.
people[].firstNamestring
A first name, where the platform matches people by name (with lastName).
people[].handlestring
A username on the platform, with or without @.
people[].lastNamestring
A last name, with firstName.
people[].phonestring
A phone number with its country code (+45 25 73 66 00).
people[].titlestring
A job title, helping a name match.
people[].xUserIdstring
A user ID on the platform (digits).

Response200 OK

acceptedinteger
Rows the platform took, where it answers row by row; absent where it doesn't say.
actionstringRequired
What was done (replaced: the list's people replaced whole, where the platform takes a list whole).One of created, added, removed, replaced, updated, deleted
adAccountIdstringRequired
The ad account.
audienceIdstringRequired
The audience at the platform.
givenintegerRequired
People the request named.
kindstringRequired
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
namestring or nullRequired
The name the request gave, when it gave one.
notestringRequired
What happens next.
sentintegerRequired
People sent to the platform (each with at least one value it can match).
skippedintegerRequired
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-After seconds. 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"
      }
    ]
  }'
GET/platforms/{platform}/bid-strategies

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
dataarray of objectsRequired
Every bid strategy that isn't removed.
data[].campaignCountinteger or nullRequired
How many campaigns follow it.
data[].campaignTypestring or null
Where the platform ties a strategy to one campaign type: the campaigns that may follow it.
data[].currencystring or nullRequired
The currency of its money targets.
data[].idstringRequired
The platform's ID: what a launch's bidding.portfolio names.
data[].namestring or nullRequired
Its name, unique in the ad account; null with withheld where the platform's terms keep it in Pluto's own app (its type, count, currency and targets too).
data[].statusstring or nullRequired
Its status at the platform.
data[].targetsobjectRequired
data[].targets.impressionSharestring
An impression share strategy: percent of impressions to aim for, 1 to 100.
data[].targets.locationstring
An impression share strategy: where on the results page.One of ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE
data[].targets.maxCpcstring
The highest bid the strategy sets, a decimal in the ad account's currency; "" clears it.
data[].targets.minCpcstring
The lowest bid the strategy sets; "" clears it.
data[].targets.targetCpastring
The cost per action to aim for, a decimal in the ad account's currency; "" clears it.
data[].targets.targetRoasstring
The return on ad spend to aim for, in percent ("350" is 350%), 1 to 100,000; "" clears it.
data[].typestring or nullRequired
Its type, in the platform's words.
typesarray of objectsRequired
The types a new strategy takes.
types[].labelstringRequired
Its name.
types[].valuestringRequired
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-After seconds. 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"
POST/platforms/{platform}/bid-strategies

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
campaignTypestring
Where the platform ties a strategy to one campaign type: the campaigns that may follow it, fixed once made (Search when left out); another platform refuses it.One of Search, Shopping
namestringRequired
Its name, unique in the ad account.
targetsobject
targets.impressionSharestring
An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.locationstring
An impression share strategy: where on the results page.One of ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE
targets.maxCpcstring
The highest bid the strategy sets, a decimal in the ad account's currency; "" clears it.
targets.minCpcstring
The lowest bid the strategy sets; "" clears it.
targets.targetCpastring
The cost per action to aim for, a decimal in the ad account's currency; "" clears it.
targets.targetRoasstring
The return on ad spend to aim for, in percent ("350" is 350%), 1 to 100,000; "" clears it.
typestringRequired
Its type (a platform that hasn't one of them refuses it on type).One of MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, TARGET_CPA, TARGET_ROAS, TARGET_SPEND, TARGET_IMPRESSION_SHARE

Response201 Created

campaignCountinteger or nullRequired
How many campaigns follow it.
campaignTypestring or null
Where the platform ties a strategy to one campaign type: the campaigns that may follow it.
currencystring or nullRequired
The currency of its money targets.
idstringRequired
The platform's ID: what a launch's bidding.portfolio names.
namestring or nullRequired
Its name, unique in the ad account; null with withheld where the platform's terms keep it in Pluto's own app (its type, count, currency and targets too).
statusstring or nullRequired
Its status at the platform.
targetsobjectRequired
targets.impressionSharestring
An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.locationstring
An impression share strategy: where on the results page.One of ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE
targets.maxCpcstring
The highest bid the strategy sets, a decimal in the ad account's currency; "" clears it.
targets.minCpcstring
The lowest bid the strategy sets; "" clears it.
targets.targetCpastring
The cost per action to aim for, a decimal in the ad account's currency; "" clears it.
targets.targetRoasstring
The return on ad spend to aim for, in percent ("350" is 350%), 1 to 100,000; "" clears it.
typestring or nullRequired
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-After seconds. 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"
  }'
PATCH/platforms/{platform}/bid-strategies/{id}

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
namestring
A new name.
targetsobject
targets.impressionSharestring
An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.locationstring
An impression share strategy: where on the results page.One of ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE
targets.maxCpcstring
The highest bid the strategy sets, a decimal in the ad account's currency; "" clears it.
targets.minCpcstring
The lowest bid the strategy sets; "" clears it.
targets.targetCpastring
The cost per action to aim for, a decimal in the ad account's currency; "" clears it.
targets.targetRoasstring
The return on ad spend to aim for, in percent ("350" is 350%), 1 to 100,000; "" clears it.

Response200 OK

campaignCountinteger or nullRequired
How many campaigns follow it.
campaignTypestring or null
Where the platform ties a strategy to one campaign type: the campaigns that may follow it.
currencystring or nullRequired
The currency of its money targets.
idstringRequired
The platform's ID: what a launch's bidding.portfolio names.
namestring or nullRequired
Its name, unique in the ad account; null with withheld where the platform's terms keep it in Pluto's own app (its type, count, currency and targets too).
statusstring or nullRequired
Its status at the platform.
targetsobjectRequired
targets.impressionSharestring
An impression share strategy: percent of impressions to aim for, 1 to 100.
targets.locationstring
An impression share strategy: where on the results page.One of ANYWHERE_ON_PAGE, TOP_OF_PAGE, ABSOLUTE_TOP_OF_PAGE
targets.maxCpcstring
The highest bid the strategy sets, a decimal in the ad account's currency; "" clears it.
targets.minCpcstring
The lowest bid the strategy sets; "" clears it.
targets.targetCpastring
The cost per action to aim for, a decimal in the ad account's currency; "" clears it.
targets.targetRoasstring
The return on ad spend to aim for, in percent ("350" is 350%), 1 to 100,000; "" clears it.
typestring or nullRequired
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-After seconds. 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"
    }
  }'
GET/platforms/{platform}/campaigns

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

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalOnly this ad account.
statusquerystringOptionalOnly this status, as the platform reports it (e.g. ACTIVE or PAUSED).
searchquerystringOptionalPart of the name, or the exact ID.
afterquerystringOptionalCursor: nextAfter from the previous page.
limitquerystringOptionalPage size, 1-500 (default 200).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

dataarray of objectsRequired
This page.
nextAfterstring or nullRequired
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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/campaigns" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/conversion-actions

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
categoriesarray of objectsRequired
The categories a new conversion action takes.
categories[].labelstringRequired
Its name.
categories[].valuestringRequired
The category.
dataarray of objectsRequired
Every conversion action that isn't removed.
data[].categorystring or nullRequired
Its category, in the platform's words.
data[].idstringRequired
The platform's ID.
data[].namestringRequired
Its name, unique in the ad account.
data[].statusstring or nullRequired
Its status at the platform.
data[].tagSnippetsarray of objectsRequired
The tag the platform generated, to put on the website; empty for a type that needs none.
data[].tagSnippets[].eventSnippetstring or nullRequired
The event snippet, for the page that counts the conversion.
data[].tagSnippets[].globalSiteTagstring or nullRequired
The site-wide tag, for every page of the site.
data[].tagSnippets[].pageFormatstring or nullRequired
The page's format the snippet is for (HTML, AMP).
data[].tagSnippets[].typestring or nullRequired
What the snippet tracks, in the platform's words (WEBPAGE, WEBPAGE_ONCLICK, CLICK_TO_CALL, WEBSITE_CALL).
data[].typestring or nullRequired
Its type, in the platform's words.
typesarray of objectsRequired
The types a new conversion action takes.
types[].callbooleanRequired
It counts calls.
types[].labelstringRequired
Its name.
types[].taggedbooleanRequired
The platform answers a tag to put on the website.
types[].valuestringRequired
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-After seconds. 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"
POST/platforms/{platform}/conversion-actions

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
alwaysUseDefaultValueboolean
Count value even when the site sends its own (always on for calls from ads and to a website number).
callSecondsinteger
Calls: how long a call lasts before it counts, 0 to 10,000 (60 when left out).
categorystring
What it counts, in the platform's words (PURCHASE, SUBMIT_LEAD_FORM, …); DEFAULT when left out.
clickThroughDaysinteger
How many days after a click a conversion counts: 1 to 90, 1 to 60 for calls.
countingstring
Every conversion after a click, or only the first.One of MANY_PER_CLICK, ONE_PER_CLICK
namestringRequired
Its name, unique in the ad account, at most 100 characters.
primaryboolean
Used for bidding as a primary action of its goal.
typestringRequired
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
valuestring
What one conversion is worth, in the ad account's currency.
viewThroughDaysinteger
How many days after a view a conversion counts: 1 to 30; none for calls.

Response201 Created

categorystring or nullRequired
Its category, in the platform's words.
idstringRequired
The platform's ID.
namestringRequired
Its name, unique in the ad account.
statusstring or nullRequired
Its status at the platform.
tagSnippetsarray of objectsRequired
The tag the platform generated, to put on the website; empty for a type that needs none.
tagSnippets[].eventSnippetstring or nullRequired
The event snippet, for the page that counts the conversion.
tagSnippets[].globalSiteTagstring or nullRequired
The site-wide tag, for every page of the site.
tagSnippets[].pageFormatstring or nullRequired
The page's format the snippet is for (HTML, AMP).
tagSnippets[].typestring or nullRequired
What the snippet tracks, in the platform's words (WEBPAGE, WEBPAGE_ONCLICK, CLICK_TO_CALL, WEBSITE_CALL).
typestring or nullRequired
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-After seconds. 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/platforms/{platform}/conversion-actions/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
idpathstringRequiredThe conversion action's ID.
adAccountIdquerystringOptionalThe ad account.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

categorystring or nullRequired
Its category, in the platform's words.
idstringRequired
The platform's ID.
namestringRequired
Its name, unique in the ad account.
statusstring or nullRequired
Its status at the platform.
tagSnippetsarray of objectsRequired
The tag the platform generated, to put on the website; empty for a type that needs none.
tagSnippets[].eventSnippetstring or nullRequired
The event snippet, for the page that counts the conversion.
tagSnippets[].globalSiteTagstring or nullRequired
The site-wide tag, for every page of the site.
tagSnippets[].pageFormatstring or nullRequired
The page's format the snippet is for (HTML, AMP).
tagSnippets[].typestring or nullRequired
What the snippet tracks, in the platform's words (WEBPAGE, WEBPAGE_ONCLICK, CLICK_TO_CALL, WEBSITE_CALL).
typestring or nullRequired
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-After seconds. 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"
POST/platforms/{platform}/conversion-goals

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The account.
appobject
App install goals: platform (Android, iOS, Windows) and storeId.
attributionModelstring
How credit is given.One of LastTouch, DataDriven
categorystringRequired
The goal's category in the platform's words (Purchase, Signup, …).
conversionWindowMinutesinteger
Minutes after a click a conversion counts: 1 to 129,600 (90 days).
countTypestring
Every conversion, or one per click.One of All, Unique
eventobject
Event goals: category, action and label (each an operator and expression) and value (operator: Equals, LessThan, GreaterThan, and value).
includeInConversionsboolean
Counted in Conversions and used for bidding.
minimumDurationSecondsinteger
Duration goals: how long a visit lasts before it counts.
minimumPagesViewedinteger
Pages per visit goals: how many pages a visit counts from.
namestringRequired
Its name, unique in the account, at most 100 characters.
revenueobject
type (FixedValue, VariableValue, NoValue) and value, a decimal in the account's currency.
scopestring
The account's own, or every account of its customer.One of Account, Customer
statusstring
Counting, or not.One of Active, Paused
tagIdstring
The site tag that tracks it (URL, duration, pages per visit and event goals).
typestringRequired
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
urlobject
operator (Equals, BeginsWith, RegularExpression, Contains) and expression.
viewThroughWindowMinutesinteger
Minutes after a view a conversion counts: 1 to 43,200 (30 days).

Response201 Created

adAccountIdstringRequired
The account.
donestringRequired
What was done.One of created, changed
idstringRequired
The goal's or tag's ID at the platform.
platformstringRequired
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-After seconds. 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
  }'
PATCH/platforms/{platform}/conversion-goals/{id}

Change a conversion goal

Changes only what the body names of a conversion goal; its type never changes.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The account.
appobject
App install goals: platform (Android, iOS, Windows) and storeId.
attributionModelstring
How credit is given.One of LastTouch, DataDriven
categorystring
The goal's category in the platform's words (Purchase, Signup, …).
conversionWindowMinutesinteger
Minutes after a click a conversion counts: 1 to 129,600 (90 days).
countTypestring
Every conversion, or one per click.One of All, Unique
eventobject
Event goals: category, action and label (each an operator and expression) and value (operator: Equals, LessThan, GreaterThan, and value).
includeInConversionsboolean
Counted in Conversions and used for bidding.
minimumDurationSecondsinteger
Duration goals: how long a visit lasts before it counts.
minimumPagesViewedinteger
Pages per visit goals: how many pages a visit counts from.
namestring
Its name, unique in the account, at most 100 characters.
revenueobject
type (FixedValue, VariableValue, NoValue) and value, a decimal in the account's currency.
scopestring
The account's own, or every account of its customer.One of Account, Customer
statusstring
Counting, or not.One of Active, Paused
tagIdstring
The site tag that tracks it (URL, duration, pages per visit and event goals).
typestring
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
urlobject
operator (Equals, BeginsWith, RegularExpression, Contains) and expression.
viewThroughWindowMinutesinteger
Minutes after a view a conversion counts: 1 to 43,200 (30 days).

Response200 OK

adAccountIdstringRequired
The account.
donestringRequired
What was done.One of created, changed
idstringRequired
The goal's or tag's ID at the platform.
platformstringRequired
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-After seconds. 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
  }'
GET/platforms/{platform}/conversions

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

Permission: read

Parameters

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

Response200 OK

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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 409The platform's connection can't be used now (reconnect it).
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/conversions" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/platforms/{platform}/conversions

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
advancedMatchingboolean
A new pixel's automatic advanced matching.
advancedMatchingFieldsarray of strings
The fields a new pixel's advanced matching uses.
clickWindowinteger
Days after a click a conversion counts: 1, 7, 14 or 30.
datasetIdstring
Where conversions are measured with datasets: the dataset a pixel or CAPI integration joins; none: one of its own.
domainstring
Where conversions are measured with datasets: a pixel's site, starting with https://.
integrationIdsarray of strings
A new dataset's pixels and CAPI integrations, by their integration ID.
namestringRequired
The event's name (up to 255 characters).
retargetingboolean
People who did it can be reached again with a tailored audience.
typestringRequired
The platform's kind of event, such as PURCHASE, SIGN_UP, ADD_TO_CART, SITE_VISIT or CUSTOM.
viewWindowinteger
Days after a view a conversion counts: 0, 1, 7, 14 or 30 (0: views don't count).

Response201 Created

adAccountIdstringRequired
The ad account.
donestringRequired
created, changed or deleted.
idstringRequired
The conversion event's ID on the platform.
platformstringRequired
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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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
  }'
PATCH/platforms/{platform}/conversions/{id}

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
clickWindowinteger
Days after a click a conversion counts: 1, 7, 14 or 30.
domainstring
Where conversions are measured with datasets: a pixel's new site.
namestring
The event's name (up to 255 characters).
retargetingboolean
People who did it can be reached again with a tailored audience.
typestring
The platform's kind of event.
viewWindowinteger
Days after a view a conversion counts: 0, 1, 7, 14 or 30.

Response200 OK

adAccountIdstringRequired
The ad account.
donestringRequired
created, changed or deleted.
idstringRequired
The conversion event's ID on the platform.
platformstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/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/platforms/{platform}/conversions/{id}

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
donestringRequired
created, changed or deleted.
idstringRequired
The conversion event's ID on the platform.
platformstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/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"
POST/platforms/{platform}/imports

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

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
adSetIdsarray of strings
Meta only.
campaignIdsarray of strings
Each becomes one launch.
dryRunboolean
Only review.
replaceChangesboolean
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.

Response202 Accepted

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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 409A refresh would replace changes made in Pluto: review, then send replaceChanges.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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/platforms/{platform}/imports/{id}

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.

Permission: read

Parameters

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

Response200 OK

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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/keyword-competition

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalRequired. The ad account.
campaignIdquerystringOptionalOnly this campaign's, by its ID at the platform.
adGroupIdquerystringOptionalOnly this ad set's (ad group's), by its ID at the platform.
qquerystringOptionalText the keyword or search term contains.
sincequerystringOptionalThe period's first day (2026-10-01), in the ad account's time zone; with until. Default: the last 30 days.
untilquerystringOptionalThe period's last day.
sortquerystringOptionalcost (default), clicks, impressions, conversions or text.
limitquerystringOptionalRows in the answer: 1 to 10000, default 500.
offsetquerystringOptionalRows to skip.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

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-After seconds. 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"
POST/platforms/{platform}/keyword-forecasts

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.

Permission: read

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
biddingobjectRequired
strategy, maxCpc, dailyBudget, decimals in the ad account's currency.
devicesarray of strings
The devices to estimate for, where the platform's planner takes them; every device when left out.
keywordsarray of objectsRequired
Up to 10,000.
languagesarray of strings
Languages.
locationsarray of strings
Any number, as the platform takes them; some need at least one.
negativeKeywordsarray of objects
Searches to leave out, where the platform's planner estimates with negatives; refused on this field elsewhere.
periodobject
since and until: starting tomorrow at the earliest, ending within a year.

Response200 OK

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-After seconds. 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": {}
  }'
POST/platforms/{platform}/keyword-ideas

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.

Permission: read

Parameters

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

Request body

adAccountIdstringRequired
The ad account whose planner to ask.
averageCpcboolean
The average CPC seen too.
historyMonthsinteger
The last 1 to 48 whole months, in place of months.
includeAdultboolean
Adult ideas too.
keywordsarray of strings
Up to 20 keywords to start from.
languagestring
A language ID.
locationsarray of strings
As many as the platform's keyword planner takes; some need at least one.
monthsobject
from and to, like 2026-03.
networkstring
Where searches are counted; default with partners.One of GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS
pageSizeinteger
Ideas per page: 1 to 10000, default 500.
pageTokenstring
The previous page's nextPageToken.
sitestring
A whole website's domain to start from, alone.
urlstring
A page of the website to start from.

Response200 OK

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-After seconds. 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"
  }'
POST/platforms/{platform}/keyword-ideas/metrics

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.

Permission: read

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
historyMonthsinteger
The last 1 to 48 whole months, in place of months.
keywordsarray of stringsRequired
The keywords.
languagestring
A language ID.
locationsarray of strings
As many as the platform's keyword planner takes; some need at least one.
monthsobject
from and to, like 2022-11.
networkstring
Where searches are counted.One of GOOGLE_SEARCH, GOOGLE_SEARCH_AND_PARTNERS

Response200 OK

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-After seconds. 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"
  }'
GET/platforms/{platform}/keywords

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalRequired. The ad account.
campaignIdquerystringOptionalOnly this campaign's, by its ID at the platform.
adGroupIdquerystringOptionalOnly this ad set's (ad group's), by its ID at the platform.
qquerystringOptionalText the keyword or search term contains.
sincequerystringOptionalThe period's first day (2026-10-01), in the ad account's time zone; with until. Default: the last 30 days.
untilquerystringOptionalThe period's last day.
sortquerystringOptionalcost (default), clicks, impressions, conversions or text.
limitquerystringOptionalRows in the answer: 1 to 10000, default 500.
offsetquerystringOptionalRows to skip.
formatquerystringOptionalcsv downloads every row (up to 50,000) with every column, the platform's column names first.
removedquerystringOptionaltrue lists removed keywords too.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstringRequired
The ad account.
currencystring
The ad account's currency: every amount is in it, never converted.
itemsarray of objectsRequired
The keywords, highest cost first by default.
platformstringRequired
The platform.
readOnlyReasonstring
Why nothing can be changed in this ad account, when that's so; null otherwise.
totalinteger
How many rows the list has in all.
truncatedboolean
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-After seconds. 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"
POST/platforms/{platform}/keywords

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
changesarray of objectsRequired
One or more changes.

Response202 Accepted

batchesintegerRequired
How many requests go to the platform: one per campaign (one per ad group where changes go per ad group).
changesintegerRequired
How many changes the request held.
jobIdstring (uuid)Required
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-After seconds. 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/platforms/{platform}/minimum-budget

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalThe ad account, as GET /platforms/{platform}/… and the integration name it.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstringRequired
The ad account.
bidMaximumstring or null
On a platform that keeps one table of minimums: the largest bid in the currency; null when none, or where withheld.
bidMinimumstring
On a platform that keeps one table of minimums: the smallest bid.
campaignSpendCapstring
On a platform that keeps one table of minimums: the smallest campaign spend cap.
campaignTypestring or null
Where the campaign holds the budget: the kind of campaign the minimum is for, in the platform's words.
currencystringRequired
The ad account's currency (ISO 4217).
dailystring or nullRequired
The minimum daily budget, a decimal string in currency; null when the platform gives none.
notestring
Where the currency shows, when it's withheld.
withheldboolean
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 from GET /platforms (e.g. meta); a platform this workspace can't use, or one that gives no minimum to read, answers 404.
  • 409The platform's connection can't be used now (reconnect it).
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/minimum-budget" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/negative-keyword-lists

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
currencystring
The ad account's currency: every amount is in it, never converted.
itemsarray of objectsRequired
The lists.
platformstringRequired
The platform.
readOnlyReasonstring
Why nothing can be changed in this ad account, when that's so; null otherwise.
totalinteger
How many rows the list has in all.
truncatedboolean
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-After seconds. 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"
POST/platforms/{platform}/negative-keyword-lists

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
changesarray of objectsRequired
The changes.

Response202 Accepted

batchesintegerRequired
How many all-or-nothing requests go to the platform.
changesintegerRequired
How many changes the request held.
jobIdstring (uuid)Required
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-After seconds. 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": [
      {}
    ]
  }'
GET/platforms/{platform}/negative-keywords

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalRequired. The ad account.
campaignIdquerystringOptionalOnly this campaign's (its own and its ad sets').
adGroupIdquerystringOptionalOnly this ad set's.
qquerystringOptionalText the negative keyword contains.
formatquerystringOptionalcsv downloads them all.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstringRequired
The ad account.
currencystring
The ad account's currency: every amount is in it, never converted.
itemsarray of objectsRequired
The negative keywords.
platformstringRequired
The platform.
readOnlyReasonstring
Why nothing can be changed in this ad account, when that's so; null otherwise.
totalinteger
How many rows the list has in all.
truncatedboolean
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-After seconds. 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"
POST/platforms/{platform}/negative-keywords

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
changesarray of objectsRequired
One or more changes.

Response202 Accepted

batchesintegerRequired
How many all-or-nothing requests go to the platform: one per campaign, and one for lists.
changesintegerRequired
How many changes the request held.
jobIdstring (uuid)Required
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-After seconds. 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": [
      {}
    ]
  }'
POST/platforms/{platform}/offline-conversions

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The account.
conversionsarray of objectsRequired
Any number: Pluto sends them 1,000 a call, Microsoft's limit.
conversions[].clickIdstring
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[].conversionNamestringRequired
The offline conversion goal it counts in, by its name.
conversions[].conversionTimestringRequired
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) with timeZone.
conversions[].currencystring
The value's three-letter currency code; none takes the goal's.
conversions[].hashedEmailstring
Enhanced conversions: the SHA-256 hash of the customer's email address, 64 hexadecimal characters.
conversions[].hashedPhonestring
Enhanced conversions: the SHA-256 hash of the customer's phone number in E.164 form, 64 hexadecimal characters.
conversions[].timeZonestring
A time zone name from the platform's list that a local conversionTime is in, with its daylight saving time.
conversions[].valuestring
What it was worth, a decimal; none takes the goal's value.

Response200 OK

acceptedintegerRequired
How many conversions the platform took.
adAccountIdstringRequired
The account.
platformstringRequired
The platform.
refusedarray of objectsRequired
The conversions the platform didn't take, by their place in conversions.
refused[].indexintegerRequired
The conversion's place in conversions, from 0.
refused[].reasonstringRequired
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-After seconds. 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"
      }
    ]
  }'
GET/platforms/{platform}/portfolios

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
dataarray of objectsRequired
The portfolios, by name.
data[].idstringRequired
The portfolio's ID at the platform.
data[].namestring or nullRequired
Its name; null where withheld.
data[].statestring or nullRequired
Its state, as the platform writes it; null where withheld.
data[].withheldbooleanRequired
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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 422No ad account named.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/portfolios" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/recommendations

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalRequired. The ad account.
campaignIdquerystringOptionalOnly this campaign's.
typequerystringOptionalOnly this type.
categoryquerystringOptionalbidding_budgets, keywords_targeting, ads_assets, automated_campaigns, measurement, repairs or other.
dismissedquerystringOptionaltrue lists dismissed recommendations instead.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstringRequired
The ad account.
currencystring
The ad account's currency: every amount is in it, never converted.
itemsarray of objectsRequired
The recommendations.
platformstringRequired
The platform.
readOnlyReasonstring
Why nothing can be changed in this ad account, when that's so; null otherwise.
totalinteger
How many rows the list has in all.
truncatedboolean
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-After seconds. 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"
POST/platforms/{platform}/recommendations/apply

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
itemsarray of objectsRequired
At least one; any number.

Response202 Accepted

jobIdstring (uuid)Required
The job.
recommendationsintegerRequired
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-After seconds. 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": [
      {}
    ]
  }'
POST/platforms/{platform}/recommendations/dismiss

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
idsarray of stringsRequired
At least one; any number.

Response202 Accepted

jobIdstring (uuid)Required
The job.
recommendationsintegerRequired
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-After seconds. 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"
    ]
  }'
POST/platforms/{platform}/recommendations/refresh

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.

Permission: write

Parameters

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

Request body

adAccountIdstringRequired
The ad account.

Response200 OK

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-After seconds. 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/platforms/{platform}/search-term-brands

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalRequired. The ad account.
campaignIdquerystringOptionalOnly this campaign's search terms.
sincequerystringOptionalThe period's first day, in the ad account's time zone; with until. Default: the last 30 days.
untilquerystringOptionalThe period's last day.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

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-After seconds. 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"
GET/platforms/{platform}/search-terms

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalRequired. The ad account.
campaignIdquerystringOptionalOnly this campaign's, by its ID at the platform.
adGroupIdquerystringOptionalOnly this ad set's (ad group's), by its ID at the platform.
qquerystringOptionalText the keyword or search term contains.
sincequerystringOptionalThe period's first day (2026-10-01), in the ad account's time zone; with until. Default: the last 30 days.
untilquerystringOptionalThe period's last day.
sortquerystringOptionalcost (default), clicks, impressions, conversions or text.
limitquerystringOptionalRows in the answer: 1 to 10000, default 500.
offsetquerystringOptionalRows to skip.
formatquerystringOptionalcsv downloads every row (up to 50,000) with every column, the platform's column names first.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstringRequired
The ad account.
currencystring
The ad account's currency: every amount is in it, never converted.
itemsarray of objectsRequired
The search terms.
platformstringRequired
The platform.
readOnlyReasonstring
Why nothing can be changed in this ad account, when that's so; null otherwise.
totalinteger
How many rows the list has in all.
truncatedboolean
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-After seconds. 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"
POST/platforms/{platform}/site-tags

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The account.
descriptionstring
What it tracks; empty clears it.
namestringRequired
Its name, at most 100 characters.

Response201 Created

adAccountIdstringRequired
The account.
donestringRequired
What was done.One of created, changed
idstringRequired
The goal's or tag's ID at the platform.
platformstringRequired
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-After seconds. 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"
  }'
PATCH/platforms/{platform}/site-tags/{id}

Change a site tag

A site tag's new name or description.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The account.
descriptionstring
What it tracks; empty clears it.
namestring
Its name, at most 100 characters.

Response200 OK

adAccountIdstringRequired
The account.
donestringRequired
What was done.One of created, changed
idstringRequired
The goal's or tag's ID at the platform.
platformstringRequired
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-After seconds. 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/platforms/{platform}/spec

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.

Permission: read

Parameters

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

Response200 OK

contentobject or nullRequired
The launch content, or null.
platformstringRequired
The platform.
versionstringRequired
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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/spec" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/stores/{store}/products

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
storepathstringRequired
adAccountIdquerystringOptionalThe ad account whose store it is.
limitquerystringOptionalProducts, 1-12 (default 4).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 409The platform's connection can't be used now (reconnect it).
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/stores/0ecbb9d6-2dc4-4046-bdce-d0c0396cbfee/products" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/targeting

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

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
adAccountIdquerystringOptionalThe 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.
facetquerystringOptionalThe facet or kind, from the platform's spec.
qquerystringOptionalWhat 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.
limitquerystringOptionalResults, 1-100 (default 25).
localequerystringOptionalThe language and country value names come in, like de_DE (default en_US), where the platform names them by locale.
identityquerystringOptionalWho the ads run as, where a facet lists that account's own posts (an existing post an ad promotes).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

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 from GET /platforms (e.g. meta); a platform this workspace can't use answers 404.
  • 409The platform's connection can't be used now (reconnect it).
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/platforms/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/targeting" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/platforms/{platform}/videos

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.

Permission: read

Parameters

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

Response200 OK

accountVideosarray of objectsRequired
The ad account's other video assets, read from the platform now.
accountVideos[].assetResourceNamestringRequired
The ad account's video asset.
accountVideos[].titlestring or null
Its title there.
accountVideos[].youtubeUrlstringRequired
The video's page.
accountVideos[].youtubeVideoIdstringRequired
The video's ID on the video site.
adAccountIdstringRequired
The ad account.
dataarray of objectsRequired
Pluto's videos of the ad account, newest first.
data[].adAccountIdstringRequired
The ad account.
data[].assetResourceNamestring or null
The ad account's video asset ads use.
data[].byteSizeinteger or null
The file's size, for an upload.
data[].channelIdstring or null
The brand channel it was uploaded to; null: the channel the platform manages for the ad account (unlisted only).
data[].createdAtstring (date-time)Required
When Pluto added it.
data[].errorobject or null
Why it failed: the platform's or Pluto's code and the sentence to show.
data[].error.codestring or null
data[].error.messagestringRequired
data[].generativeContentstring or null
What the upload declared: whether the video was made or changed with AI.One of NON_GENERATIVE_CONTENT, GENERATIVE_CONTENT
data[].idstring (uuid)Required
Pluto's ID of the video in this ad account.
data[].mediaIdstring (uuid) or null
The media library video, for an upload.
data[].privacystringRequired
Who can find it on the video site.One of UNLISTED, PUBLIC
data[].removedAtstring (date-time) or null
When Pluto removed it.
data[].sentBytesinteger or null
The bytes sent so far, while uploading.
data[].sourcestringRequired
upload: a media library video publishing put on the platform's video site. youtube: a video already there, added by its link.One of upload, youtube
data[].statusstringRequired
ready once ads can use it.One of uploading, processing, ready, failed
data[].titlestring or null
The title it was uploaded with, or the site's title of a video added by link.
data[].uploadStatestring or null
The platform's own state of the upload.One of PENDING, UPLOADED, PROCESSED, FAILED, REJECTED, UNAVAILABLE
data[].youtubeUrlstring or null
The video's page.
data[].youtubeVideoIdstring or null
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-After seconds. 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"
POST/platforms/{platform}/videos

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
The ad account.
videostringRequired
The video's link or ID.

Response200 OK

codestringRequired
Stable code.One of bad_request, unauthenticated, forbidden, not_found, conflict, invalid, rate_limited, unavailable, internal
currentobject
The current entity, on a stale expectedVersion (409).
errorsarray of objects
Every field problem (422).
errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
errors[].fieldstringRequired
JSON-pointer-like path.
errors[].messagestringRequired
Problem.
errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
requestIdstring
The request's ID, as in the x-request-id header. Include it when you report a problem.
statusintegerRequired
HTTP status.
titlestringRequired
What went wrong, for the person or agent reading it.
titleCodestring
A registered title's stable code (such as not_found_the_launch), for an app to say the title in its language; absent for a title without one. title reads the same either way.
titleParamsobject
The values titleCode's sentence names, present exactly when titleCode is.
traceIdstring
The request's trace ID, as in the x-trace-id header.
typestringRequired
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 carries current), 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-After seconds. 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"
  }'
PATCH/platforms/{platform}/videos/{id}

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

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

privacystringRequired
Who can find it on the video site.One of UNLISTED, PUBLIC

Response200 OK

adAccountIdstringRequired
The ad account.
assetResourceNamestring or null
The ad account's video asset ads use.
byteSizeinteger or null
The file's size, for an upload.
channelIdstring or null
The brand channel it was uploaded to; null: the channel the platform manages for the ad account (unlisted only).
createdAtstring (date-time)Required
When Pluto added it.
errorobject or null
Why it failed: the platform's or Pluto's code and the sentence to show.
error.codestring or null
error.messagestringRequired
generativeContentstring or null
What the upload declared: whether the video was made or changed with AI.One of NON_GENERATIVE_CONTENT, GENERATIVE_CONTENT
idstring (uuid)Required
Pluto's ID of the video in this ad account.
mediaIdstring (uuid) or null
The media library video, for an upload.
privacystringRequired
Who can find it on the video site.One of UNLISTED, PUBLIC
removedAtstring (date-time) or null
When Pluto removed it.
sentBytesinteger or null
The bytes sent so far, while uploading.
sourcestringRequired
upload: a media library video publishing put on the platform's video site. youtube: a video already there, added by its link.One of upload, youtube
statusstringRequired
ready once ads can use it.One of uploading, processing, ready, failed
titlestring or null
The title it was uploaded with, or the site's title of a video added by link.
uploadStatestring or null
The platform's own state of the upload.One of PENDING, UPLOADED, PROCESSED, FAILED, REJECTED, UNAVAILABLE
youtubeUrlstring or null
The video's page.
youtubeVideoIdstring or null
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 carries current), 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-After seconds. 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"
  }'
DELETE/platforms/{platform}/videos/{id}

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
assetResourceNamestring or null
The ad account's video asset ads use.
byteSizeinteger or null
The file's size, for an upload.
channelIdstring or null
The brand channel it was uploaded to; null: the channel the platform manages for the ad account (unlisted only).
createdAtstring (date-time)Required
When Pluto added it.
errorobject or null
Why it failed: the platform's or Pluto's code and the sentence to show.
error.codestring or null
error.messagestringRequired
generativeContentstring or null
What the upload declared: whether the video was made or changed with AI.One of NON_GENERATIVE_CONTENT, GENERATIVE_CONTENT
idstring (uuid)Required
Pluto's ID of the video in this ad account.
mediaIdstring (uuid) or null
The media library video, for an upload.
privacystringRequired
Who can find it on the video site.One of UNLISTED, PUBLIC
removedAtstring (date-time) or null
When Pluto removed it.
sentBytesinteger or null
The bytes sent so far, while uploading.
sourcestringRequired
upload: a media library video publishing put on the platform's video site. youtube: a video already there, added by its link.One of upload, youtube
statusstringRequired
ready once ads can use it.One of uploading, processing, ready, failed
titlestring or null
The title it was uploaded with, or the site's title of a video added by link.
uploadStatestring or null
The platform's own state of the upload.One of PENDING, UPLOADED, PROCESSED, FAILED, REJECTED, UNAVAILABLE
youtubeUrlstring or null
The video's page.
youtubeVideoIdstring or null
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/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/integrations/{platform}

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.

Permission: read

Parameters

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

Response200 OK

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-After seconds. 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"
PUT/integrations/{platform}/ad-accounts/{id}/sync

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

enabledbooleanRequired
true turns it on, false off.

Response200 OK

adAccountIdstringRequired
Account.
enabledbooleanRequired
Whether it's on now.
jobIdstring (uuid) or nullRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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
  }'
POST/integrations/{platform}/connect

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

reconnectboolean
Sign in again for an existing connection instead of connecting.
returnTostring
Where the app opens after the consent, a path such as /integrations (the default).

Response201 Created

authorizationUrlstringRequired
The consent page for the person to open in their browser (single use).
expiresAtstring (date-time)Required
The URL stops working after this.
personIdstring (uuid) or nullRequired
The person who must open the URL, signed in to Pluto Ads.
statusstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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"
  }'
POST/integrations/{platform}/disconnect

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Response200 OK

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/disconnect" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 05474409-509d-4229-ab79-41d318ee90f1"
PUT/integrations/{platform}/pages/{id}/enabled

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

enabledbooleanRequired
true turns it on, false off.

Response200 OK

enabledbooleanRequired
Whether it's on now.
pageIdstringRequired
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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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
  }'
POST/integrations/{platform}/sync

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstring
Only this ad account, where supported.
adIdstring
Only this synced ad, where supported.
adSetIdstring
Only this synced ad set, where supported.
campaignIdstring
Only this synced campaign, where supported.

Response200 OK

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