Public API
The Pluto Ads REST API: the same API the app uses, for your scripts, servers and integrations.
Everything a person does in the app, your code can do with its own credential, through the same actions, permissions and audit log. This page covers what every request shares. Each endpoint, with its fields and examples, is in the API reference.
Quickstart
Create a key in SettingsAPI (Settings, then API) with New API key, and choose Edit access. See Create an API key. Then set two variables:
export PLUTO_API=https://api.plutoads.ai/api/v1
export PLUTO_KEY=sk_live_...List the workspace's launches:
curl -s "$PLUTO_API/launches?limit=2" \
-H "Authorization: Bearer $PLUTO_KEY"Create a launch. The Idempotency-Key makes a retry safe:
curl -s "$PLUTO_API/launches" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: holiday-gift-sets-2026" \
-d '{"name": "Holiday gift sets, US"}'The answer is 201 with the new launch and its version. Next, add ad sets and ads, then publish: see the
Launches reference.
Authentication
Send a credential on every request as Authorization: Bearer <credential>.
| Credential | Starts with | For |
|---|---|---|
| Secret API key | sk_live_ | Scripts and servers. Has the scopes chosen when it was created. |
| Publishable API key | pk_live_ | Read-only integrations. Has read only. |
| Access token | Agents people connect from Claude, ChatGPT or Cursor, and agent credentials. |
A key belongs to one workspace and needs no workspace header. A token that reaches several workspaces chooses one
with Pluto-Workspace: <workspace ID>. A credential sent to a workspace it doesn't belong to gets 403.
Every credential acts for a person, and never does more than that person can do right now. If their role changes, the credential follows on its next request. If they leave, it stops.
Scopes
| Scope | Allows |
|---|---|
read | Reading launches, ads, media, results and settings |
review | Commenting, and approving or requesting changes on ads. Mentioning a guest on a launch that isn't shared with guests shares it, which also needs write. |
write | Drafts, edits, media, workflow and settings |
publish | Publishing launches and every change to what runs on the ad platforms: delivery, budgets, bids, schedules, targeting, copies and deletes, and replies to comments on ads |
admin | This workspace's members and guests, API keys, webhooks, the ad platform connections and settings |
organization | The organization's people, workspaces, plan, billing and usage limits. Comes with admin. |
Publishing spends money, so it's its own scope: a key with write never changes a live ad. A secret key created
through the API gets read, review, write and publish unless you name its scopes. Each endpoint's reference
names the scope it needs. A credential can also hold single capabilities by ID, like ads:publish, beside or
instead of these: the app's Access picks them. See Access.
Each scope holds a set of capabilities, one for each kind of thing you may do. For example, publish holds
ads:publish (publishing and pushing edits), budgets:write (live budgets, bids and schedules), delivery:write
(pausing and resuming), ads:delete (deleting in the ad platform) and social:write (comments on live ads). A
refused request names the capability it needed in missingCapability (see
forbidden). GET /me lists a person's capabilities in each workspace and what their
organization role allows in each organization they belong to (organizations), and MCP's get_context lists a
credential's own.
A credential's scopes can also name single workspace capabilities, for exactly what it needs: a key with
["ads:read", "delivery:write"] reads and pauses or resumes ads, and nothing else. Ask for what each capability
requires beside it: delivery:write needs ads:read (or the read scope), and a request without it is 422,
naming it. Organization access stays the organization scope, with admin. A scope you don't hold yourself is refused with 422
capability_not_grantable, naming the capability in missingCapability.
An API key's or agent credential's view (GET /api-keys, GET /agent-clients and what creating one answers) lists
effectiveCapabilities: what it can do now, its scopes within its person's current role and what your organization
lets members' API keys or agents hold. narrowedBy says why that's less than its scopes: role, policy or
expired, and is empty when it can use every scope.
API access is included on every plan, the free trial too. An organization without a plan is read-only: reads work,
and changes answer 402 payment_required.
Expiry and allowed addresses
API keys and agent credentials take two more limits when you create them:
expiresAt(RFC 3339): when the credential stops working by itself, within two years. Without it, it lasts 90 days, or your organization's limit when that's shorter. Sendnullfor a credential that never expires, which an organization's limit doesn't allow (422).allowedIps: up to 20 addresses (203.0.113.7) or CIDR ranges (198.51.100.0/24,2001:db8::/32) it works from. A request from anywhere else gets403, the credential's last use stays as it was, and the audit log records the refused address (once a minute per credential and address).
curl -s "$PLUTO_API/api-keys" \
-H "Authorization: Bearer $PLUTO_KEY" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "name": "Reporting server", "kind": "secret", "scopes": ["read"],
"expiresAt": "2027-02-02T00:00:00Z", "allowedIps": ["203.0.113.7"] }'Rotating a key keeps its expiry and addresses. Revoking a credential also revokes the keys and agent credentials it created, and turns off the webhooks it created, so a leaked key takes everything it made down with it.
To give a credential less access without replacing it, narrow it: PATCH /api-keys/{id}, /agent-clients/{id} or
/agent-connections/{id} with scopes, what it keeps. It keeps its secret, client and tokens, and from its next
request does only that. A scope it doesn't hold now is 422: narrowing never adds access. What it made keeps its own
access. Organization owners and admins narrow any credential in the organization with
PATCH /organizations/{id}/credentials/{credentialId}.
Ad accounts
API keys, agent credentials and connected agents work in every ad account of their workspace, or in chosen ones:
resources: { "adAccounts": ["act_123", "508123"] } when you create one (POST /api-keys, /agent-clients), when a
person consents to an agent, and when you narrow one (PATCH, beside scopes). The IDs are the workspace's ad
accounts on any platform, as list_platforms names them (Meta's act_..., X's ad account ID). Without resources a credential
gets what its maker reaches (a person every ad account); "all" says so explicitly. An ID that isn't one of the
workspace's ad accounts, or one the caller doesn't reach, is 422 on resources.adAccounts, and narrowing keeps only
fewer, never more.
curl -s "$PLUTO_API/api-keys" \
-H "Authorization: Bearer $PLUTO_KEY" -H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "name": "US agency", "kind": "secret", "scopes": ["read", "write", "publish"],
"resources": { "adAccounts": ["act_123"] } }'A credential with chosen ad accounts:
- Reads only what's in them. Anything in another ad account answers
404, as if it didn't exist, and lists leave it out: launches, ads and ad sets, the platforms' campaigns, ad sets and ads (name one of its ad accounts inadAccountIdto list them), insights, leads from their ads, and the jobs it started itself. - Is refused acting on anything in another ad account, or naming one for something new (a launch, an import, a
refresh):
403withtitleCodeforbidden_outside_ad_accounts, recorded in the audit log. Queued work it started checks again when it runs. - Sees what has no ad account of its own only when everything it's about is in them: inbox items, Agent chats, loops and their runs, plans (change sets) and bulk edits, Creative Memory's experiments and monitors. One about nothing in an ad account (a notice, a loop set to every ad account) stays hidden from it.
- Sees people's data by where it came from: leads and comments on ads' posts by their ad; organic leads, lead forms and comments on a Page's other posts only when every ad account that publishes from that Page is one of its own.
- Reads or syncs what spans every ad account at once (Pluto Profit's store summary and product profitability, reading
every Page's leads or comments now, a sync without
adAccountId, an insights import withoutadAccountIds, and a platform's sync that always covers every ad account) only when it reaches every one of them; otherwise403withforbidden_outside_ad_accounts. - Works with what's in no ad account as before: the media library, drafts without an ad account, the workflow.
- Holds nothing that spans every ad account, whatever its
scopessay: the Agent, loops, members, integrations, everyone's credentials, the audit log and the organization. ItsnarrowedBysaysresources. - Creates webhooks that deliver only its ad accounts' events (
adAccountIdson the webhook), and credentials that reach no more ad accounts than it does. It manages only webhooks within its ad accounts.
Every credential's view says what it reaches: resources: { "adAccounts": "all" }, or each ad account with its id,
name and platform. An agent reads its own in get_context (credential.resources).
An organization can limit what its members do with credentials (credentialPolicy on
PATCH /organizations/{id}, for its owners and admins, who it doesn't bind). Each setting you leave out keeps its
value:
membersMayCreateApiKeys,membersMayCreateAgentClientsandmembersMayCreateWebhooks:falselets only the organization's owners and admins create that kind. A member who tries gets403, saying so in one sentence. What members made before keeps working.membersAgentAccess:full(up to their role),build(what the app's Build and publish gives: viewing, launches and drafts, media, reviews, publishing, live budgets, pausing and resuming) orview(only viewing), for members' own agents. It applies on their agents' next request.membersAgentClientAccessandmembersApiKeyAccess: the same for the agent credentials and API keys members are accountable for. A new one beyond it is refused with422invalid, the problem underscopessaying what the organization allows, and nomissingCapability: the role allows it, the organization doesn't. One made before is narrowed on its next request, itsnarrowedBysayingpolicy; its scopes stay as they are, so choosingfullagain gives back what it had. UntilmembersAgentClientAccessis set, agent credentials followmembersAgentAccess.maxLifetimeDays: new credentials members make end within that many days. WithoutexpiresAtthey end at the limit when it's shorter than 90 days, and asking for more, or fornull, is refused.
Agent credentials
Agent credentials are a client ID and secret for your own agent or service, created in SettingsAPI (Settings, then API). Your
service trades them for a short-lived access token (OAuth client credentials) and asks for a new one when
expires_in runs out. The token endpoint is found from the API's metadata, so nothing is hard-coded:
AUTH_SERVER=$(curl -s "$PLUTO_API/.well-known/oauth-protected-resource" | jq -r '.authorization_servers[0]')
TOKEN_URL=$(curl -s "$AUTH_SERVER/.well-known/oauth-authorization-server" | jq -r '.token_endpoint')
curl -s "$TOKEN_URL" \
-d grant_type=client_credentials \
-d client_id="$CLIENT_ID" \
-d client_secret="$CLIENT_SECRET" \
-d resource="$PLUTO_API/mcp"The token works for this API and the MCP server. Keep resource: a token asked for without it, or for
another resource, answers 401 unauthenticated.
To change the secret, POST /agent-clients/{id}/rotate: the answer holds the new clientSecret, once, and the
clientId stays. The old secret gets no more tokens, and tokens it got answer 401 from their next request, so your
service asks for a new one with the new secret. The credentials aren't revoked, so what they made keeps working; to end
that too, revoke them instead.
Base URL and versions
Every endpoint is under https://api.plutoads.ai/api/v1. The API version is part of the path. The OpenAPI 3.1
document at $PLUTO_API/openapi.json describes every endpoint.
- Requests and responses are JSON, with camelCase fields.
- IDs are UUIDs, except the ad platforms' own IDs, written as each platform writes them: on Meta,
act_and digits for ad accounts and digits for campaigns, ad sets and ads. - Times are RFC 3339 in UTC.
- Amounts are decimal strings in the ad account's currency, like
"49.99". A JSON number where an amount belongs is a400.nullmeans unknown, never zero.
Idempotency
Every change is a command. Send an Idempotency-Key of 1 to 200 characters, and reuse it when you retry the same
request. A retry after a timeout returns the stored result and changes nothing.
- Derive keys from your own records (
holiday-gift-sets-2026), not a random value per attempt. - Keys are remembered for 30 days, per credential.
- The same key with a different body is a
409withreason:command_id_reused. - Batch endpoints take
items[], each with its owncommandIdthat works the same way, and return an outcome per item:accepted,rejectedwith itserrors, orconflict. Resend only what failed.
Without the header a request still runs once, but a retry can't be recognized and may act twice.
Versions and conflicts
What you can edit, like launches, ad sets, ads and media, has a version. Send the version you last read as
expectedVersion when you update it.
Launches, ad sets and ads track versions per field: an update from an older version still applies when nobody
changed the fields it touches. When someone did, the answer is 409 with the current state in current. Merge,
then retry with expectedVersion set to current.version.
Pagination
Lists take limit and after, and answer with items and nextAfter. Pass nextAfter as after for the next
page. It's null on the last page.
curl -s "$PLUTO_API/launches?limit=50&after=$NEXT_AFTER" -H "Authorization: Bearer $PLUTO_KEY"Each endpoint's reference gives its default and largest limit, and the few lists shaped differently.
Rate limits
Limits count requests in 10-second windows.
| Who | Requests per 10 seconds |
|---|---|
| Each API key or agent | 1,000 |
| All API keys and agents of one workspace together | 3,000 |
| Each person in the app | 300 |
People in the app don't count toward the workspace's total, so busy agents never slow them down. Over a limit, the
answer is 429 with a Retry-After header in seconds. Wait that long, then retry with the same idempotency key.
A few endpoints have their own limits: Creative Memory search runs 4 searches at once per workspace, and refreshing
analytics starts at most 2 imports per workspace every 15 minutes. Name the ad accounts you need with adAccountIds
and the import reads only those, so it finishes sooner. Publishing jobs pace themselves to each ad platform's limits.
Errors
Errors are application/problem+json with a stable code. type links to the code's section in
API errors.
{
"type": "https://docs.plutoads.ai/api/errors#invalid",
"title": "The request has 1 problem.",
"status": 422,
"code": "invalid",
"errors": [{ "field": "name", "message": "Use a name of 1 to 120 characters." }]
}Every response has x-request-id and x-trace-id headers, and every error repeats them as requestId and traceId.
Include them when you report a problem.
Insights
GET /analytics/insights answers with the numbers the Analytics dashboard shows, for since and until (days in each
ad account's time zone), optionally compared with compare_since and compare_until.
attribution:7d_click_1d_view(Meta's default: each ad set's own attribution setting, as in Ads Manager),7d_click,1d_click,28d_clickor1d_view.- Object filters:
adAccountId,campaignId,adSetId,adId,launchId(and their names:account,campaign,adSet,launch). Repeat a parameter for alternatives; different parameters combine. - Segment filters:
age(25-34),gender(female),country(US),region,placement(instagram|story),publisherPlatform(instagram),impressionDevice,devicePlatform,hour(00to23) andformat(the ad format of a flexible or dynamic creative ad). Filter by one breakdown at a time: age and gender together, or one of the others. Segment filters use Meta's default attribution setting, and a comparison is made only when the segment rows cover the comparison period too (comparisonIncompleteotherwise). breakdown: rows perlaunch,campaign,adSetorad, or per segment:age,gender,ageGender,country,region,placement,publisherPlatform,impressionDevice,devicePlatform,hour,actionDevice,actionDestination,actionType,bodyAsset,titleAsset,imageAsset,videoAsset,callToActionAsset,linkUrlAsset,adFormatAssetorproduct; and Meta'sdma,platformDevice(instagram|iphone),viewerHour(the hour in the viewer's time zone),actionReaction,actionVideoSound,actionVideoTypeandactionCarouselCard(a card by its name).- Metrics include every action Meta counts:
action:<type>(a count),action_value:<type>(its value) andcost_per_action:<type>, for exampleaction:offsite_conversion.custom.1234567890. Ad rows carry Meta'srankings(quality,engagementRate,conversionRate, withasOf).
Meta keeps numbers per segment for 13 months; coverage.breakdowns says, per breakdown, which days are in (from,
through: the last day read to its end, and readAt), which rows answered (level: account for whole ad
accounts, back 13 months; ad for a read narrowed to a campaign, ad set, ad or launch, whose segment rows cover the
last two weeks), the days Meta couldn't produce (unreadDays, which keep the numbers they had) and which ad accounts
haven't turned a breakdown on in Ads Manager. A measure Meta doesn't split by a breakdown is absent from its rows, never filled in from the totals, and
reach, frequency and unique clicks are absent per segment. Meta splits no website or app conversion (purchases, their
value, carts, checkouts, landing page views) by region, dma, viewerHour, product or an action breakdown: those
answers carry a note saying so (segmentsNote for such a filter), and the conversions are absent, never 0.
While Pluto reads an ad account's older days again with newer fields (action types, video plays, watch time,
rankings), coverage.history.fieldsCompleteFrom (and each account's history.fieldsCompleteFrom) is the first day
every field is in. A metric read from those fields over a period starting earlier has incomplete: true, every
entry of actionMetrics too, breakdown.incomplete for breakdown=actionType and breakdown.rankingsIncomplete
for breakdown=ad.
With platform=linkedin, the segments are LinkedIn's: jobTitle, jobFunction, seniority, industry,
companySize, company, country, region and county (its member demographics, values as LinkedIn's IDs) and
conversionAction (a conversion rule's ID), placement, device, servingLocation (ON_SITE, OFF_SITE,
UNKNOWN) and carouselCard (the card's index from 0), each read on its own; breakdown takes any of them and
each row's name is LinkedIn's name for the value (English, empty when LinkedIn hasn't given one). Rows carry the
shared metrics and LinkedIn's own (engagements, qualified_leads, open_rate and the rest). Demographics are
approximate (none under 3 events), 24 to 48 hours late and reported for ad sets and up: with an adId or launchId
filter they answer 422, and they have no conversion_value or roas. Their figures are LinkedIn's for exactly the
period at the level filtered (ad account, campaignId or adSetId), read from LinkedIn the first time a period is
asked: breakdown.basis is period, or days when LinkedIn didn't answer in time and the daily rows were added up.
With a demographic filter, demographics.totals says the same of the totals, and the series are the daily rows.
Their spend isn't adjusted for over delivery (spendAdjustedForOverDelivery: false), so it can add up to more than
was billed. A demographic period starting more than 6 months ago must be whole months (422 otherwise), as LinkedIn
keeps daily demographics 6 months. A conversion action splits only the conversions, a device has no conversions,
and reach and frequency are absent per segment. LinkedIn's segments reach back 365 days.
curl -s "$PLUTO_API/analytics/insights?since=2026-10-13&until=2026-11-11&breakdown=placement" \
-H "Authorization: Bearer $PLUTO_KEY"Asking for exactly what you need
metric: only these metrics, everywhere the answer has metrics (repeat it:metric=spend&metric=roas). Any ID of the platform's catalogue works, andaction:<type>on Meta. An ID the platform doesn't report answers422with the closest IDs it does have.definitions=true(implied bymetric): each metric's definition indefinitions: itsnameon the platform,unit(money,count,fraction,multiple,seconds), how it adds up (aggregation) and whether it'ssummable.summetrics add up across days, rows and accounts.ratiometrics are recomputed from the sums, never averaged.windowmetrics (reach, frequency, unique clicks) are the platform's own figure for exactly the period and object: they never add up, so breakdown rows don't sum to the total.- With a
breakdown:sortorders the rows by a metric (descending;-spendtoo,order=ascfor ascending; rows without a value come last),limit(1 to 1000) pages them, andcursortakes the previous answer'sbreakdown.nextCursor(null on the last page).breakdown.rowsTotalcounts every row in scope. status(repeatable) keeps only ads with that status in the platform's words (ACTIVEis delivering now,PAUSED), andlabelIdorlabelonly the ads Pluto labelled so: every figure, totals included, then covers just those ads.thenBysplits every breakdown row again: byday,weekormonth(ad by day, country by week), or, with a breakdown by launch, campaign, ad set or ad, by a segment the platform reports (campaign by country). Each row getsby.rows, each{ key, metrics }from its own sums: summed metrics add up to the row, ratios are recomputed, and reach, frequency and unique counts are never in a sub-row, since they don't add up.platforms(names comma-separated, orallfor every connected platform) answers several platforms at once: each platform's own answer underbyPlatform, never added together, since each reports its own currencies, days and attribution.withheldPlatformsandrefusedname any platform that can't give numbers here, and why.
curl -s "$PLUTO_API/analytics/insights?since=2026-10-13&until=2026-11-11&breakdown=campaign&metric=spend&metric=roas&sort=spend&limit=20" \
-H "Authorization: Bearer $PLUTO_KEY"Ranking ads
GET /analytics/rankings ranks one platform's ads by a metric on the server, over every ad in scope, and answers
the same as the MCP tool rank_ads for the same arguments. Use it for the top or bottom ads instead of reading a whole
ad breakdown.
periodnames the days (last_30_daysby default,last_7_days,this_month,all_timeand others), or givesinceanduntil.metricis what to rank by (spendby default): any per-ad metric the platform reports, andaction:<type>orcost_per_action:<type>on Meta.orderisdescorasc; by default the best come first, so costs rank lowest first.limit(1 to 50, default 10) andoffsetpage each ranking;nextOffsetis the next page's offset.- Filters:
adAccountId,campaignId,adSetId,adIdandlaunchId(repeat them for several), the segment filters above by name,status(ACTIVE: running now),minSpend,minPurchasesandcurrency. SetminSpendfor ROAS or cost rankings, so ads with a single result don't lead. metrics(repeat it, orall) picks the metrics each ad carries;creative=falseleaves out what Creative Memory found in its files, andposts=trueadds a Meta ad's Facebook and Instagram post links.
Every other parameter comes once, and an unknown one answers 422. Money is ranked within one currency: rankings
has one entry per currency, each with adsInScope, totals and its ads in items, every ad with its name, campaign,
ad set, links and metrics.
curl -s "$PLUTO_API/analytics/rankings?period=last_month&metric=roas&minSpend=500" \
-H "Authorization: Bearer $PLUTO_KEY"Results kept in Pluto
Some platforms' terms let their results show only inside Pluto's own app: on X, its numbers, names and statuses. An
answer outside the app (the API, MCP, AI agents, exports) has those values as null and says why in withheldData,
one entry per platform, with the platforms in the Pluto-Withheld header too:
{
"withheld": true,
"withheldData": [{
"reason": "platform_terms",
"platform": "x",
"platformName": "X",
"message": "The X terms don't let Pluto share X results outside Pluto's own app: not through the API, MCP, AI agents or exports. The results exist and are complete in Pluto; a null here is not missing data and not zero. The person sees them in Pluto: https://app.plutoads.ai/<workspace>/analytics?platform=x. Retrying, or asking another tool or endpoint, gives the same answer. Still usable here: the IDs of the X objects, the names, labels and launches Pluto owns, the statuses Pluto set, and every other platform's data.",
"appUrl": "https://app.plutoads.ai/<workspace>/analytics?platform=x",
"dataExists": true,
"retryable": false,
"stillAvailable": ["The IDs of the X ad accounts, campaigns, ad groups and ads", "Names, labels and launches Pluto owns", "Statuses Pluto set", "Every other platform's data"]
}]
}The results exist and are complete in Pluto: the nulls are not missing data or zero. Asking again, here or through
another endpoint or tool, gives the same answer. Send the person to appUrl, and keep working with the IDs, Pluto's
own records and every other platform's data.
Ad platforms
A launch publishes to Meta or LinkedIn or X. GET /platforms lists the platforms the workspace can use, each with its
own words, what Pluto Ads can do there (capabilities) and what its terms allow (policy). Pass a platform's
platform value wherever a route takes platform. Without it, a route means Meta.
- A LinkedIn launch sets
"platform": "linkedin"and a LinkedIn ad account when it's created. Its campaign and ad set settings go inplatformSettings, with the fields, options and rules ofGET /platforms/linkedin/spec.GET /platforms/linkedin/targetingsearches LinkedIn's audience values. - Reads take
platform:GET /analytics/insights,GET /changes,GET /leads, and the synced campaigns, ad sets and ads atGET /platforms/linkedin/campaigns,/ad-setsand/ads. - The connection is
GET /integrations/linkedin, withPOST /integrations/linkedin/syncandPOST /integrations/linkedin/disconnect.POST /integrations/linkedin/connectreturns a consent URL for a person to open in their browser. An API key can't connect. - LinkedIn's numbers use UTC days (
dayBasisisutc) and count each conversion in its conversion rule's windows, soattributionisnull. FromsettlingFromon, LinkedIn may still change the numbers. GET /analytics/insightswithplatform=linkedincarries every metric LinkedIn reports beside the shared ones, in the totals and every breakdown row: engagements, reactions, likes, comments, shares, follows, lead form opens, qualified leads, sends, opens, registrations, job applications, video starts and watch time (seconds), document and carousel card views, the viral (earned) figures, the rates and costs over them (such asopen_rateandcost_per_qualified_lead), andaverage_dwell_timeandaudience_penetrationas LinkedIn's figures for exactly the period (the windows reach is read for) when the scope is one ad account, campaign or ad set. Segments: see Insights.
curl -s "$PLUTO_API/launches" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wholesale-partners-fall-2026" \
-d '{
"name": "Wholesale partners, fall",
"platform": "linkedin",
"adAccountId": "512345678",
"platformSettings": {
"campaign": { "objective": "WEBSITE_VISIT" },
"adSet": { "page": "80412345", "dailyBudget": "50.00" }
}
}'-
The X connection is
GET /integrations/x, withPOST /integrations/x/syncandPOST /integrations/x/disconnect.POST /integrations/x/connectreturns a consent URL for a person to open in their browser. An API key can't connect.PUT /integrations/x/ad-accounts/{id}/syncturns an ad account on or off, andPUT /integrations/x/pages/{id}/enabledan X account ads run as (identitiesandidentitiesOffin the connection). -
X's terms keep what Pluto Ads reads from X inside Pluto Ads (
policy.dataLeavesUiisfalseinGET /platforms). In the connection, an ad account'sname,currency,timeZone,approvalStatusand role, an X account'susernameandname, the payment methods' values (fundingSources) andnoticesarenull, and the object says so withwithheld: true. IDs,status,scopes,lastSyncandcredits(what the workspace's X API calls cost this month against its allowance) are there as on any platform. -
One X account connects to one organization: a consent for an X account that another organization has connected returns to the app with
x=error&reason=other_organization, and nothing changes for either. -
An X launch sets
"platform": "x"and an X ad account when it's created. Its settings go inplatformSettings:campaignholds the campaign's,adSetwhat every ad group starts with, and an ad group's ownplatformSettingsonly the keys it changes.GET /platforms/x/spechas the fields, options, limits and rules.
| Level | Keys |
|---|---|
campaign | objective, fundingSource, dailyBudget, totalBudget, purchaseOrderNumber |
adSet | identity (the X account's user ID), promotedOnly, whoCanReply, start, end, dailyBudget, totalBudget, acceleratedDelivery, goal, bidStrategy, bidAmount, payBy, frequencyCap, frequencyDays, conversionEvent, iosAppId, androidAppId, placements, advertiserDomain, categories, audienceExpansion, audience, trackingTags, leadForm |
- Amounts are decimal strings in the ad account's currency. The campaign's budgets cap what its ad groups spend
together.
nullempties a key, and on an ad group it goes back to the launch's value. - A write refuses what X wouldn't take with
422and X's reason on the field, such asplatformSettings.adSet.bidAmount. What's still to fill in is saved and listed byGET /launches/{id}/publish, which checks everything X would: X has no test run of its own. - An ad is the launch's own: its text is the Post text, 280 characters with a link counting as 23, and its media,
headline, link and button decide what X shows.
settings.utmis added to each link as it's written, since X fills in no values. GET /platforms/x/targetingsearches X's audience values withfacetset to one of the spec's targeting types,qandadAccountId.GET /platforms/x/conversions?adAccountId=lists the ad account's conversion events.POST /platforms/x/audience-estimatewithadAccountIdand an ad group'saudienceasks X how many people it reaches (min,max;estimableisfalsefor an audience of only locations, age, gender, language and devices).GET /platforms/x/ad-previews?adId=takes up to 25 ads, by their Pluto or X IDs, and answers X's own preview of each one's Post. To an API key both answerwithheld: truewith the numbers and the previewnull, and X isn't asked: the estimate and the previews show in Pluto.- The synced campaigns, ad groups and ads are at
GET /platforms/x/campaigns,/ad-setsand/ads.POST /platforms/x/importsbrings campaigns in as launches (dryRunonly reviews them), andGET /platforms/x/imports/{id}reports on it. - X's terms keep what Pluto reads from X inside Pluto. In an answer to an API key or an agent, a field holding what
X reports (a name, a status, a figure) is
null, andwithheldbeside it istrue: X results show in Pluto. IDs, your launches and drafts, and the outcome of what you asked Pluto to do answer as always. - Live changes use the same routes as on Meta. An X ad can't be edited in place:
POST /ads/{id}/statuswithPAUSEDremoves the ad from its ad group on X andACTIVEadds the same Post again, and a pending change to its text, media, headline, link, button or cards replaces the ad on X when it's published.GET /launches/{id}/revisionssays so on that change.
curl -s "$PLUTO_API/launches" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: spring-sale-x-2026" \
-d '{
"name": "Spring sale",
"platform": "x",
"adAccountId": "18ce54d4x5t",
"settings": {
"primaryTexts": ["Spring is here"],
"headlines": ["Shop the spring sale"],
"websiteUrl": "https://example.com/spring"
},
"platformSettings": {
"campaign": { "objective": "WEBSITE_CLICKS", "fundingSource": "lygyi", "dailyBudget": "100.00" },
"adSet": {
"identity": "1500000000000000001",
"dailyBudget": "40.00",
"audience": { "locations": [{ "id": "96683cc9126741d1", "name": "United States" }] }
}
}
}'X's defaults and settings templates use the same routes with x as the platform:
GET /defaults/xanswerscampaignandadSetin X's keys (the table above),launchwith the workspace's X settings (utm,replies,leadSync) andaccountswith each X ad account's defaults, keyed by its ID.PATCH /defaults/x/campaignand/ad-settake the keys every X ad account shares.fundingSource,identity,conversionEvent,leadFormand the dates belong to one launch or ad account and answer422, and so do the values each ad account keeps (purchaseOrderNumber,iosAppId,androidAppId,advertiserDomain,categories,trackingTags): set those per ad account.PATCH /defaults/x/accounts/{accountId}takessettingswith the keys to change for that ad account (identity,fundingSource,conversionEvent,purchaseOrderNumber,iosAppId,androidAppId,advertiserDomain,categories,trackingTags), andDELETEon the same address clears them. The X account and funding source must be the ad account's own. A new launch on the ad account takes them where it has none of its own. X's ad accounts share oneversioninaccounts.PATCH /defaults/x/launchtakesutm(written out: X fills no values in a link, so{{...}}is refused),repliesandleadSync. Withrepliesoff, replies to the workspace's ad Posts aren't read (each read costs X API credits). WithleadSyncoff, leads aren't read, and lead forms still work.POST /setting-templateswith"platform": "x"holds campaign or ad group keys, never what names one ad account's objects.fromsaves an X ad group or campaign without them.campaignTemplateIdonPOST /launchesandtemplateIdonPOST /launches/{id}/ad-setsstart from one, andPOST /setting-templates/{id}/applyapplies one to X ad groups or launches.GET /platforms/x/account-settings?adAccountId=reads an ad account's tax settings, your contact settings and its apps from X. Like everything X reports, the values arenullwith"withheld": trueoutside the app.
X's terms keep what Pluto Ads reads from X inside the app (policy.dataLeavesUi is false on GET /platforms), so
the API tells you what there is and never the figures:
GET /analytics/insights?platform=xanswers the platform, period, labels and import state, withmetrics,byCurrency,breakdownanddefinedMetricsnull,"withheld": trueand"note": "X results show in Pluto.". X's numbers use the ad account's days (dayBasisisaccount) and count each conversion in its conversion event's windows (attributionBasisisconversionEvent), soattributionisnull.GET /changes?platform=xlists every change. A change Pluto made (source: pluto) carries its values; a change found on X (source: platform) hasfrom,to, its description and the object's name left out and"withheld": true. What changed, when and the X IDs stay.GET /analytics/segments?platform=xanswers"rows": nulland"withheld": true.POST /analytics/refreshwith"platform": "x"imports the last two days now, as for every platform.
X's numbers are kept for 90 days and deleted when X is disconnected.
On X, lead forms and replies use the same routes with "platform": "x":
- Lead forms.
POST /leads/formscreates a form on an X ad account:adAccountId,name,purpose(why you collect the details, shown on the form),fields(X's field keys such asEMAILandFULL_NAME, each once, at least one notoptional),privacyPolicy(urlstarting withhttps://, andcompanyName), and optionallyintroductionandfinalPage.PATCH /leads/forms/{id}changes what the body names;fields,privacyPolicy,introductionandfinalPageare each replaced whole.DELETE /leads/forms/{id}archives the form, which X can't undo. Each returns202with a job, and X's rules are checked first: a422names the field. - Leads. X sends no lead webhook, so Pluto Ads reads new leads from X every 15 minutes, or when you call
POST /leads/syncwith"platform": "x". X hands leads to the ad account's Account administrator only: when the connected X user has another role,access.lastErrorsays so and the forms are still listed. - Replies. On X a comment is a reply.
GET /social/comments?platform=xlists the replies to your ads' Posts;POST /social/comments/{id}/hide,/unhideand/replieshide, show and answer one as the connected X account, on ads that run as that account. X doesn't let anyone delete someone else's reply, soDELETE /social/comments/{id}takes only your own. A reply is written by a person: a reply sent by an agent or an MCP client is refused, because X needs to approve AI-written replies first. - What stays in Pluto Ads. X's terms keep what it reports inside Pluto Ads' own app. Through the API, a lead, a
form and a reply answer with their IDs, times and what Pluto Ads did, with
withheld: true: a lead's answers, a form's name and questions, and a reply's text arenullor empty. Open Pluto Ads to read them. Pluto Ads keeps what it read from X for 90 days at most and deletes it when you disconnect X. - X API credits. Reading and answering replies costs X API credits.
access.creditson the replies list shows what the workspace used this month (spentUsd) against its allowance, andattentionholds one line when the allowance runs low: replies are then read less often, and from 75% only when you ask.
Pluto Profit
With Pluto Profit connected, your code can read whether the store's ads make money. Each workspace connects one store, and Pluto Ads only reads from Pluto Profit: it never changes anything there.
GET /profit/summaryhas the store's profit for a period,GET /profit/productswhat each product left after its costs and the ad spend allocated to it, andGET /profit/adsan estimate per Meta ad, ad set or campaign. Passsinceanduntilas days in the store's timezone, at most 366 days apart.- Money is decimal strings: store and product figures in the store's currency, ad estimates in each ad
account's currency. A value Pluto Profit can't compute, for example because a cost
is missing, is
null. It never means zero. - Pluto Profit reports profit per store and per product, not per ad.
GET /profit/adsestimates it from the store's break-even ROAS and the purchase value Meta attributes to each ad, and every answer says so withestimate: trueand itsbasis. GET /integrations/pluto-profithas the connection and how current the store's data is. Without a working connection, the profit routes answer409.- Admins connect.
POST /integrations/pluto-profit/authorizereturns an approval URL for a person to open in their browser, so it needs a credential that acts for a person; an API key gets403. To connect with a Pluto Profit API key instead, usePOST /integrations/pluto-profit/connect. - Guests never see profit.
Webhooks
A webhook sends a signed POST to your HTTPS endpoint when something changes in the workspace. Admins create
them in SettingsAPI (Settings, then API) or with POST /webhooks. The signing secret is shown once.
POST /hooks/pluto HTTP/1.1
Host: hooks.brevanne.com
Content-Type: application/json
User-Agent: PlutoAds-Webhooks/1
Pluto-Event: launch.changed
Pluto-Delivery: 01a0d7ea-73c8-7141-88fc-ca7e0a0f499b
Pluto-Signature: t=1790613261,v1=b2715e3196cd794c2f5da6d1d7d6265311e548dbee524ee6af3dfc9fb2a52034
{"id":"cbc4a711-9e0b-5c60-8991-f6b58af28200","event":"launch.changed","workspaceId":"01a0d7e5-acb8-7176-a698-b6947a8016fe","occurredAt":"2026-09-28T16:34:21Z","data":{"launchId":"01a0d8da-b21b-741f-9bdf-e0d0a8846c39","version":8}}The payload names what changed. Read the current state through the API. Delivery is at least once, so skip an
id you've already handled.
Verify the signature. Pluto-Signature is t=<unix seconds>,v1=<hex HMAC-SHA256>, computed with the whole
whsec_... secret over <t>.<raw body>. Check it over the raw bytes, before parsing, and reject old timestamps.
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the exact bytes received (a Buffer), before any JSON parsing.
export function verifyPlutoSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
const timestamp = Number(parts.t);
if (!Number.isInteger(timestamp) || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
const received = Buffer.from(parts.v1, "hex");
return received.length === expected.length && timingSafeEqual(received, expected);
}Deliveries. Answer with any 2xx within 10 seconds. Anything else is retried after 30 seconds, 2, 10 and 30
minutes, then 1, 2 and 4 hours: 8 attempts in all. Each webhook's deliveries and their responses are in the app and
at GET /webhooks/{id}/deliveries.
Who it answers to. A webhook delivers only while the person accountable for it may manage webhooks in the
workspace: the person who created it, or for one an API key or agent created, that key's or agent's person while it
still works. If their role stops including it, or they lose access, nothing is sent, retries of earlier events
included, and GET /webhooks shows delivering: false with notDelivering saying why. It starts again by itself once
they may manage webhooks again. Events in between aren't sent later.
Events. Subscribe to 1 to 50 events, or to * for every event, including ones added later.
GET /webhooks/events lists them with a description each.
| Events | When they fire |
|---|---|
launch.changed, launch.deleted | A launch or its settings changed, or a draft was deleted |
launch.published, launch.publish_failed | Publishing finished, or stopped with failed items |
ad_set.changed, ad.changed, ad.deleted | An ad set or ad was created, changed, moved, deleted or archived |
ad.review_changed | The ad platform's review of a published ad changed |
meta.campaign.status_changed, meta.ad_set.status_changed, meta.ad.status_changed | A status in Meta changed, including changes made in Ads Manager |
meta.object.changed | Someone other than Pluto (a person in Ads Manager or another app) changed a campaign, ad set, ad or the ad account's spending limit in Meta: field, from, to, currency and who (changedBy) |
campaign.status_changed, ad_set.status_changed, ad.status_changed, ad_object.changed | The same status changes and outside changes under platform-neutral names, with the platform in platform. Meta sends both. |
metric.threshold_crossed, budget.spent | A metric or budget crossed a threshold set in a loop |
comment.created, comment.updated, comment.deleted, comment.restored, comment.resolved, comment.reopened | Your team's comments on ads |
social.comment.created | Someone commented on the post an ad runs as |
lead.received | Someone submitted a lead form on a connected Page, or one of an X ad account's lead forms: on X the event carries IDs and times, and the form's name stays in Pluto Ads. platform names the ad platform when it isn't Meta |
media.uploaded | An image or video is ready to use |
workflow.changed | Review statuses, tags, copy templates or country groups changed |
integration.changed | A connection was connected, synced or needs attention |
job.completed, job.failed, job.cancelled | Long-running work finished |
POST /webhooks/{id}/test sends a webhook.test event, and POST /webhooks/{id}/rotate-secret replaces the
secret at once. A workspace can have up to 20 webhooks. A webhook stops for good when the person who created it, or
whose key or agent did, loses access to the workspace: suspended, removed or gone.
Audit log
Every change people, agents, loops and keys made, with who did it, the person it was for, where it came from and
who approved it. The audit log comes with Business and Enterprise (402 plan_limit on other plans).
GET /audit-logis the workspace's log, for its admins. A credential needsadmin.GET /organizations/{id}/audit-logis the organization's: its plan, billing, credits and limits, members, invitations and credentials, whichever workspace the change came from. For the organization's owners and admins. A credential needs theorganizationscope.- Both take the same filters:
actorKind,actorId,person,origin,originId,loopId,targetType,targetId,action(exact, or a prefix ending in.),commandId(theIdempotency-Keya change was sent with),since,untilandq. They're newest first, ororder=oldest, a page at a time withafter. - Each entry has a
summarysentence, anddetailwith what changed where it says more:beforeandafter,changes, areason, arole,scopes, anamountandcurrency, aplan, and the IDs it touched.detailnever holds a secret, and has an email only on an entry about that invitation or person.qfinds words in names, the action anddetail, never in anything an entry doesn't show. requestIdnames the request or tool call an entry came from: thex-request-idthe API answered it with. Entries recorded before requests were kept have none.
Audit log exports
Export the log as CSV with POST /audit-log/exports, or POST /organizations/{id}/audit-log/exports for the
organization's from one of its workspaces. The body takes the list's filters and gzip (true for .csv.gz), and
the export runs in the background:
curl -s -X POST "$PLUTO_API/audit-log/exports" \
-H "Authorization: Bearer $PLUTO_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: audit-q3" \
-d '{"since": "2026-07-01T00:00:00Z", "until": "2026-10-01T00:00:00Z", "gzip": true}'- It answers
202with the export:id,jobId,status(queued,running,doneorfailed),rowsTotalonce the entries are counted androwsWrittenas they're written. Asking again with the same filters while one is queued or running returns that one. - Follow it with
GET /audit-log/exports/{id}, or the job withGET /jobs/{id}. Once it'sdone, the export hasdownloadUrl, a link to the file for 15 minutes. Read the export again for a new link. - Downloads end 7 days after the export was written (
expiresAt). - The person who asked gets an Inbox notice when it's ready. When it runs longer than 30 seconds or holds more than
250,000 entries, or the app's page that asked for it was left before it was ready (
emailWhenReady), they get an email at their account's address too, with a link to sign in and download it. An export that fails says so in the Inbox, never by email. - The file holds the entries as they were when the export was asked for, newest first unless
orderisoldest. Each export is in the audit log itself:audit_log.export_requestedandaudit_log.exported.
The columns, in this order (new ones only ever come at the end):
| Column | What it holds |
|---|---|
id | The entry's ID |
time | When it happened, ISO 8601 in UTC with microseconds: 2026-11-04T10:15:02.123456Z |
workspace_id, organization_id | Where it happened; organization_id on changes to the organization |
action | The stable action name, such as live.budget_changed |
summary | The sentence the audit log page shows |
actor_kind, actor_id, actor_name | Who acted: person, api_key, agent or system |
on_behalf_of_id, on_behalf_of_name | The person accountable: themself, the person an agent acts for, a key's creator |
credential_kind, credential_id, credential_name | The credential it came through: api_key, agent_client or agent_connection (empty for people and Pluto) |
origin, origin_id | Where it came from (app, api_key, mcp, agent_chat, loop, system), and the chat or loop run |
approved_by_id, approved_by_name | Who approved it, if someone did |
target_type, target_id, target_name | What it changed |
detail | The entry's detail as JSON, empty when it has none |
command_id, request_id | The command (its Idempotency-Key) and the request it came from |
The file starts with a UTF-8 byte order mark, so Excel reads accented and non-Latin letters correctly. A program
reading the file skips the mark: in Python, open it with encoding="utf-8-sig". Cells follow RFC 4180, and lines end
in CRLF. A number, such as a Meta ID in target_id, is written as it is; other text is always quoted, and an empty
cell is empty. So that no spreadsheet runs a cell as a formula, whatever its list separator, a ' goes in front of a
=, +, -, @, tab or carriage return that starts a cell, or that follows a comma, semicolon, tab or line break
inside one, even after spaces or quotes: x;'=HYPERLINK(...). In detail, such a character is written as its JSON
escape instead (= as \u003d), so detail is always the same JSON.
Workspace exports
Export a workspace's launches, ad sets and ads as CSV in the background with
POST /organizations/{id}/workspaces/{workspace_id}/exports (gzip: true for .csv.gz). It needs organization admin
access (a credential needs the organization scope), for any workspace of the organization, also an archived one or
one scheduled for deletion, and runs in the workspace your credential works in, which must be an active one of the same
organization (409 otherwise):
curl -s -X POST "$PLUTO_API/organizations/$ORGANIZATION/workspaces/$WORKSPACE/exports" \
-H "Authorization: Bearer $PLUTO_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: export-brevanne" -d '{}'- It answers
202with the export (kind: "workspace"):id,jobId,status,rowsTotalonce the rows are counted androwsWrittenas they're written. Asking again for the same workspace while its export is queued or running returns that one. - Follow it with
GET /exports/{id}, or the job withGET /jobs/{id}. Once it'sdone, the export hasdownloadUrl, a link to the file for 15 minutes; downloads end 7 days later (expiresAt). - The person who asked gets an Inbox notice when it's ready, and an email when it ran longer than 30 seconds or holds
more than 250,000 rows, or the app's page that asked for it was left before it was ready (
emailWhenReady). An export that fails says so in the Inbox, never by email. Once the file is written, the export is recorded in the exported workspace's audit log (workspace.exported). - The file is the one
GET /organizations/{id}/workspaces/{workspace_id}/export/ads.csvstreams: the same columns, the same order and the same CSV rules as the audit log's (a byte order mark first). The media originals stay a streamed download,GET .../export/media.zip.
Usage exports
Export the organization's usage events as CSV in the background with POST /organizations/{id}/usage/exports. The
body takes the events list's filters (period, or from and to; workspaceId, userId, source, loopId,
agentId, model, q), bom and gzip. It comes with Business; members export their own usage, and whoever can
view the organization's billing exports everyone's. It runs in the workspace your credential works in, an active one
of the organization:
curl -s -X POST "$PLUTO_API/organizations/$ORGANIZATION/usage/exports" \
-H "Authorization: Bearer $PLUTO_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: usage-october" -d '{"period": "previous"}'- It answers
202with the export (kind: "usage"), followed withGET /exports/{id}orGET /jobs/{id}as a workspace export is:rowsWrittenofrowsTotal, thendownloadUrlonce it'sdone, for 7 days. Asking again with the same filters while one runs returns that one. - The file is what
GET /organizations/{id}/usage/exportstreams: the same columns, the same events, oldest first. It has no byte order mark unless you ask for one withbom: true, for a person opening it in a spreadsheet. - The person who asked gets an Inbox notice when it's ready, and an email when it ran longer than 30 seconds or holds
more than 250,000 events, or the app's page that asked for it was left before it was ready. Once the file is
written, the organization's audit log records it (
billing.usage_exported).
Attach files to Agent messages
Files attached to an Agent message are kept apart from the media library: they never show up there. They're
private to the person whose chat it is, so they need a person's session or an agent acting for one (API keys get
403). Upload in three steps:
curl -s -X POST "$PLUTO_API/workspaces/$WORKSPACE/chat-files" \
-H "Authorization: Bearer $PLUTO_TOKEN" -H "Idempotency-Key: brief-q4-pdf" -H "Content-Type: application/json" \
-d '{"name": "brief.pdf", "contentType": "application/pdf", "sizeBytes": 482113}'| Kind | Types | Up to |
|---|---|---|
image | PNG, JPEG, WebP, GIF, HEIC, HEIF | 30 MB |
pdf | 100 MB | |
document, presentation | Word (.docx), PowerPoint (.pptx) | 100 MB |
spreadsheet | Excel (.xlsx), CSV, TSV | 50 MB |
text, code | Plain text, Markdown, JSON, XML, YAML, HTML and source code | 10 MB |
audio | MP3, M4A, WAV, OGG, WebM, FLAC, up to 2 hours | 200 MB |
video | MP4, MOV | 2 GB |
archive | ZIP, up to 200 files and 500 MB unpacked | 200 MB |
Send ready files with a message: POST /agent/chats/{chatId}/messages with their IDs in context.fileIds, next to
text. Media library items go in context.mediaIds. A message carries up to 20 files in all. A file that's still
being prepared is a 409, so wait for ready. A file that failed, or that isn't yours, is a 422.
curl -N -X POST "$PLUTO_API/agent/chats/$CHAT/messages" \
-H "Authorization: Bearer $PLUTO_TOKEN" -H "Idempotency-Key: ask-brief-q4" -H "Content-Type: application/json" \
-d '{"text": "What budget does this brief ask for?", "context": {"fileIds": ["'$FILE'"]}}'The message comes back with its attachments. Each has a name and kind, and either a fileId with
sizeBytes, contentType, pageCount and previewUrl (a path on the app's origin that redirects to a thumbnail,
when the file has one), or a mediaId for a media library item.
A file that can't be attached is a 422 with code invalid, a reason
(unsupported_type, too_large, empty or bad_name) and a message such as "This file is too large. The
limit is 30 MB." A new file must fit your organization's storage, like media (402 plan_limit), and starting
uploads is limited per person (429, see rate limits).
previewUrl(andGET .../preview) answers a thumbnail (a JPEG that never changes for the file, so browsers keep it): images, videos, the first page of a PDF, and Office files that saved one.GET .../contentredirects to the original.pageCountis set for PDFs, Word documents and presentations;durationMsfor videos and audio.- A zip's files are listed in
children, each with its own status. Files inside a zip inside the zip aren't opened, and a zip whose files don't fit your storage fails with a message saying so. - Attached files count toward your organization's storage from the moment the upload starts. They're never deleted automatically. An upload that isn't completed within two hours fails, and stops counting if its bytes never arrived.
Editing a message
Edit any of your own messages in a chat and continue from it, as in the app:
POST /agent/chats/{chatId}/messages/{messageId}/edit, with the same body as sending a message. It answers with
the same event stream.
- An answer that's still running stops first, as with
POST /agent/chats/{chatId}/stop. What it already did stays done, and its usage stays billed. - The new text becomes the message's next version. Everything after the message leaves the conversation, and Agent
answers with the history up to the edited message. Attachments in
contextreplace the message's. - Nothing is deleted. Every message has
versionandversions(both1unless it was edited).GET /agent/chats/{chatId}/messages/{messageId}/versionslists a message's versions, andPOST /agent/chats/{chatId}/messages/{messageId}/versionwith{"version": 1}switches to another one. Each version keeps the answers that followed it. - Only the person who sent a message can edit it (
403). An answer that doesn't stop in time is a409, so try again. Switching versions while an answer runs is a409too. - Editing never refunds or re-charges earlier answers. The new answer is billed like any other.
- MCP:
edit_agent_chat_message,list_agent_chat_message_versionsandselect_agent_chat_message_version.
curl -N -X POST "$PLUTO_API/agent/chats/$CHAT/messages/$MESSAGE/edit" \
-H "Authorization: Bearer $PLUTO_TOKEN" -H "Idempotency-Key: edit-q2" -H "Content-Type: application/json" \
-d '{"text": "Which ad set spent the most last week?"}'Retrying an answer
Run any answer again, not only the last one, as in the app:
POST /agent/chats/{chatId}/messages/{messageId}/retry with the answer's ID. It answers with the same event stream,
starting with the new version.
- The new answer becomes the answer's next version. The answer and everything after it leave the conversation and
stay with the earlier version. Nothing is deleted.
GET /agent/chats/{chatId}/messages/{messageId}/versionsandPOST /agent/chats/{chatId}/messages/{messageId}/versionwork on answers too. - Agent answers the question before it again, with the files it had, as the person who asked it.
- Send
{"model": "...", "effort": "..."}to run it on another model (the chat keeps it from then on), or no body. - A question's ID is a
422: edit the question instead. While an answer runs, or for an answer that isn't in the conversation now, it's a409. - Earlier versions keep their usage. The new answer is billed like any other.
POST /agent/chats/{chatId}/retrystill runs the last answer again in place when it failed or was stopped.
Questions and selections
When a wrong guess would cost something, Agent may ask before it acts. It asks one question with two to four
choices, or proposes a list of options to confirm, such as the ad sets it would pause. Its answer then has status
awaiting_user, with the question or the options in parts:
- A question is a part with
typequestion, itstextandchoices(id,label,description). Answer it withPOST /agent/chats/{chatId}/parts/{partId}/answerand{"choiceId": "2"}. - A selection is a part with
typeselection, atitle,options(id,label,detail) and theproposedoption IDs. Confirm exactly the ones you keep withPOST /agent/chats/{chatId}/parts/{partId}/selectand{"optionIds": ["..."]}. An empty list confirms none. - Either becomes your next message, and Agent continues. Both answer with the same event stream as sending a
message. The part then records your reply:
answerandchoiceId, orselected. - You can always reply in your own words with
POST /agent/chats/{chatId}/messagesinstead. An open question then records your words as itsanswer. - A selection changes nothing by itself. Agent acts on what you confirmed with its usual tools, and asks for approval where it always does.
- A question that was already answered, or a chat that moved on, is a
409.
Approvals sent to your Inbox
A member's Agent may propose an action their role leaves out. Proposed in their own chat, which nobody else opens, it
goes to the Inbox of the workspace's members who hold what deciding it needs: an item with kind approval, the
action as its title, who asked as its actor, and approval (id, status, decidedBy). It never holds the
chat.
GET /agent/approvals/{id}is the approval's own card: itseffectas the chat's card has it,capability,proposedBy,decidedBy,expiresAt, andcanDecidewhile you holdcapabilityand may use the Agent. Anyone it wasn't sent to gets a404, the person who asked included.POST /agent/approvals/{id}/decisionwith{"decision": "approve"}, or"reject"with an optionalreason, decides it there and answers with the card. Approving runs the action once, as you. Withoutcapabilityit's a403naming it, and approving a day after it was proposed is a409that runs nothing. Retried with the sameIdempotency-Key, the decision is replayed.- The person who asked sees the outcome in their chat, and their answer continues.
While an answer streams
Besides the events described above, the stream sends stall when an answer seems stuck: messageId and stall,
with a kind and since (when the silence began, in epoch milliseconds). no_first_byte means the model sent
nothing for 10 seconds, silent_stream that an open stream sent nothing for 15 seconds, and silent_tool that a
tool reported nothing for 45 seconds. The next stall event with stall null says it moves again. Stalls are
never stored.
The answer's steps carry a category saying what kind of call each was: write (added something), edit
(changed or removed something), read, list, search, or mcp with server naming the other Pluto product it
called. Narration and thinking have none, and neither do steps from before it was recorded.
Web search in Agent answers
Agent searches the web and reads pages when a question needs it. Nothing turns it on or off per message.
- The answer's
stepsincludekindsearch(label"Searching the web", then "Searched the web";detailis the query) andkindfetch(label"Reading example.com", then "Read example.com";detailis the page's URL).toolisnullfor both. A step that failed hasstatusfailed. - The answer's
sourceslists the pages it used:url,titleandsite(the hostname withoutwww.). Cited pages come first, in the order they were first cited, then pages it read without citing. Each URL appears once.sourcesis an empty list when the answer didn't use the web. - While an answer streams, a
sourcesevent carriesmessageIdand the whole list so far. Replace what you have. Thedoneevent's message andGET /agent/chats/{chatId}return the final list. - Each search uses credits. See Models and rates.
Charts and tables in Agent answers
Agent can show a chart or a table in its answer, drawn by the app. Agent sends the data. Every value has to come from what Pluto's tools returned in the chat, and a chart with a value Pluto can't find there is never shown.
- The answer's
partslists them in the order shown, each withtypechart, anidand akind:line,bar,horizontal-bar,stacked-bar,stacked-area,donut,funnel,combo,simple-bar,simple-normalized,spark-line,spark-barortable. A chart hasdata, a list of series (name, anddatawith each point'skeyandvalue;valueisnullwhere there is none). Acombochart hasgroups, and a table hascolumnsandrows.title,description,valueFormat(styledecimal,percentorcurrencywithcurrency,notation, fraction digits,unit),xAxisandyAxissay how it reads. Percent values are percentages:12.5is 12.5 %. partsis an empty list for most answers.- What the Agent writes before ads or a chart it shows is a
textpart (idandtext, Markdown), inpartsbefore the cards; the message'stextis what it wrote after them. - While an answer streams, a
partevent carriesmessageIdand the part. A part with anidyou already have replaces it. Thedoneevent's message andGET /agent/chats/{chatId}return every part. - A chart shows at most 7 series plus one named "Other", 60 points per bar series, 150 per line series and a table 50 rows. Agent sums up larger data first and says how.
Ads in Agent answers
Agent can show ads in its answer as cards. It names the ads, and Pluto reads each one in your workspace: an ad of another workspace is never shown.
- Each is a part with
typeads, anid, an optionaltitle, theperiodits numbers cover (since,until, andpresetsuch aslast_30_days), anditems, the ads in the order shown. - An item has the ad's
name, an optionallabel(one line over its card),metaAdId, the Pluto ad it opens (launchIdandadId,nullwhen no launch manages it) andadsManagerUrl. mediais its media library file (id,kindimageorvideo,durationMs), ornullwithout one. Read the file withGET /media/{id}/preview?variant=preview(its picture, the JPEG itself once the file is ready) orvariant=original(a redirect to a short-lived URL).clipis the part of a video the card plays:startMs,endMsandsource.hookis where Creative Memory found the hook,startis its first 5 seconds andaskedis a moment Agent chose.nullplays the whole video.metricshas the ad'scurrencyand itsspend,roasandcpafor the period as decimal strings, eachnullwhen Meta reported none. It isnullwhen the ad had no delivery in the period.- An answer shows up to 12 ads per part. Like charts, a part streams as a
partevent.
Good to know
- Long work, like publishing or importing, returns a job. Follow it with
GET /jobs/{id}, or with webhooks. Nothing is live in Meta or LinkedIn or X until the job confirms it. - Canceling a job with
POST /jobs/{id}/cancel, or retrying one withPOST /jobs/{id}/retry, needs what its work needs as it runs: a live change what it changes (delivery:writeto pause or resume,budgets:writefor budgets, bids and dates,ads:deleteto delete),ads:publishfor publishing and every other change to what runs,integrations:writeandbudgets:writefor a spending limit, andlaunches:writefor anything else. Queued work checks the same again before each item runs, on every platform: what its person can no longer do fails that item and is in the audit log. - Reactions, following, the Inbox and view preferences act for a person. API keys get
403there. - Agent model IDs come from
GET /agent/models.plutoalways runs the latest Pluto version;pluto-1stays on Pluto 1.PUT /agent/models/visibilitysets which models a person's picker shows. - Browser requests with a session are checked for the app's origin. Keys and tokens have no origin rule.
- An ad set's settings can be sent as one flat
settingsobject (POST /launches/{id}/ad-sets,PATCH /ad-sets/{id}): locations, ages, gender, audience, performance goal, pixel and event, attribution, budget, cost or bid cap, ROAS goal, devices, placements, delivery and the EU advertiser, withstartandendfor the schedule.budgetandbidAmountneedcurrency, which must be the ad account's: amounts are never converted. newCampaignonPATCH /launches/{id}merges key by key, so{"bidStrategy": "COST_CAP"}changes only the bid strategy.- Values the editor doesn't offer (a gender, placement, attribution window or call to action that isn't on the
list, an amount that isn't a decimal) are a
422naming the field. - Agents can use all of this through the MCP server.