API reference

Changes

Publishing launches to their ad platform and controlling what is live.

GET/changes

Change history

The change history of one platform (platform, default meta; the same as GET /meta/changes for Meta). Other platforms' changes come from Pluto (source: pluto) or were found on the platform (source: platform, who.kind: platform), carry the platform's own IDs (object.id) and keep their values only as long as the platform's terms allow (valuesRemoved). For Meta: every change to the workspace's Meta campaigns, ad sets, ads and ad account spending limits, newest first, whoever made it: a person, the Agent, a loop, an API key or an MCP client in Pluto (source: pluto), a person in Ads Manager or Meta's apps (meta_ui), another app (other_app) or Meta itself (meta_system: review, learning, delivery). Each change has its old and new value (money as a decimal string and as integer minor units, with its currency) and who made it (who). Name one scope: objectId (a Meta ID; act_… for the account), adId, adSetId, launchId, campaignId or adAccountId; without one, every ad account over the last 30 days. fresh=true reads Meta's newest activity for one object or account first. Keyset-paged: pass nextAfter as after.

Permission: read

Parameters

NameTypeRequiredDescription
platformquerystringOptionalA platform from GET /platforms (default meta).
objectIdquerystringOptionalA campaign, ad set or ad by Meta ID, or the ad account (act_…).
adIdquerystringOptionalA Pluto ad (its Meta ad).
adSetIdquerystringOptionalA Pluto ad set (its Meta ad set).
launchIdquerystringOptionalA launch: its campaign and everything in it.
campaignIdquerystringOptionalA campaign by Meta ID, with its ad sets and ads.
adAccountIdquerystringOptionalEverything in one ad account.
whoquerystringOptionalComma-separated: person, agent, loop, mcp, api_key, pluto, meta_user, meta_app, meta.
sourcequerystringOptionalComma-separated: pluto, meta_ui, other_app, meta_system.
fieldquerystringOptionalComma-separated: budget, status, bid, targeting, creative, ...
sincequerystringOptionalFrom this time on (RFC 3339).
untilquerystringOptionalBefore this time (RFC 3339).
freshquerystringOptionaltrue: read Meta's newest activity for the object or account first.
afterquerystringOptionalCursor: nextAfter from the previous page.
limitquerystringOptionalPage size (1-200, default 50).
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

itemsarray of objectsRequired
Changes, newest first.
items[].atstring (date-time)Required
When it happened.
items[].currencystring or null
The amounts' currency.
items[].decisionobject or null
What led to a Pluto change: the chat and model, or the loop's version, step and reason.
items[].descriptionstring or null
Meta's words for it.
items[].eventTypestring
Meta's event type, or what Pluto sent.
items[].fieldstringRequired
What changed.One of budget, spend_cap, account_spend_cap, status, delivery, bid, bid_strategy, targeting, creative, name, schedule, optimization, created, review, learning, labels, billing, other
items[].fromstring or null
The old value (money as a decimal string).
items[].fromMinorstring or null
The old amount in the currency's minor units (an integer).
items[].idstringRequired
The change's ID.
items[].levelstringRequired
What it changed.One of account, campaign, ad_set, ad
items[].metricsobject or null
The object's metrics over the 7 days before a Pluto change.
items[].objectobjectRequired
items[].object.adAccountIdstringRequired
The ad account (act_…).
items[].object.adSetIdstring or null
Its ad set's Meta ID.
items[].object.campaignIdstring or null
Its campaign's Meta ID.
items[].object.entityIdstring (uuid) or null
Its ad or ad set in Pluto, if Pluto published it.
items[].object.idstring
The object's ID on its platform (platforms other than Meta).
items[].object.launchIdstring (uuid) or null
The launch that published it, if Pluto did.
items[].object.metaIdstring
The Meta ID (Meta's history).
items[].object.namestring or null
Its name.
items[].periodstring or null
daily or lifetime for budgets.
items[].platformstring
The platform, on histories of platforms other than Meta.
items[].sourcestringRequired
Where it came from (platform: found on a platform other than Meta, in its own tool, another app or the platform itself).One of pluto, meta_ui, other_app, meta_system, platform
items[].tostring or null
The new value (money as a decimal string).
items[].toMinorstring or null
The new amount in the currency's minor units (an integer).
items[].valueKindstring
How to read from and to. creative: a live ad's creative content as JSON text (text, headline, description, cta, url, media, and for a carousel cards [{media, headline, description, url}] with bestCardsFirst and endCard, and urlTags); from is null when the content before wasn't recorded.One of money, status, text, json, creative, none
items[].valuesRemovedboolean
The platform's terms limit how long its values are kept: from, to and the name were removed after that.
items[].whoobjectRequired
items[].who.applicationstring or null
The app Meta says it came through.
items[].who.applicationIdstring or null
That app's Meta ID.
items[].who.approvalIdstring (uuid) or null
The approval that let it run.
items[].who.idstring or null
A Pluto person, agent, key or loop ID, or Meta's user ID.
items[].who.kindstringRequired
Who made it.One of person, agent, loop, mcp, api_key, pluto, meta_user, meta_app, meta, platform
items[].who.loopIdstring (uuid) or null
The loop.
items[].who.metaActorNamestring or null
Who Meta says made it.
items[].who.namestring or null
Their name.
items[].who.onBehalfOfstring (uuid) or null
The person a Pluto change was made for.
items[].who.originstring or null
Where a Pluto change came from (app, api_key, mcp, agent_chat, loop).
items[].who.originIdstring (uuid) or null
The Agent chat or loop run.
items[].withheldboolean
The platform's terms keep what is read from it inside Pluto's own app: from, to, the description and the name of a change found on the platform are left out here.
nextAfterstring or nullRequired
Pass as after for the next page; null on the last.
readAtstring or null
When the ad account's activity log was last read in full (one account asked).

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/changes" \
  -H "Authorization: Bearer $PLUTO_KEY"