Meta
The Meta connection, ad accounts, Pages, imports and changes to what's live in Meta.
Get the Meta connection
Meta connection, ad accounts and Pages.
Meta's connection, its ad accounts and Pages. For a caller with views:write whose credential reaches all of Meta, reading it also keeps the data current: when the last sync is older than 15 minutes and none is waiting, one background sync is queued, paced as the scheduler's own; the answer doesn't wait for it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountLimit- Ad accounts the last sync didn't add because the plan connects no more (Pro and the trial: 3 Meta ad accounts per organization; the cap counts per platform):
message,details(the same as a402 plan_limitwithfeature: ad_accounts:feature,reasonplan_caportrial,limit,used,plan,nextAction,upgradeTo,upgradeUrl) andheldBack[{id, name}]. Accounts already connected always stay. Null when none are waiting; on a plan that takes them, the next sync adds them. adAccounts- The ad accounts that are on: synced, counted against the plan's cap and offered everywhere in Pluto.
adAccounts[].accountStatus- Meta's account status.
adAccounts[].attention- What Meta needs a person to do in Meta before this ad account takes more changes; null when nothing.
adAccounts[].attention.blocking- Whether it stops changes (a review or an overdue payment doesn't yet).
adAccounts[].attention.checkable- Whether
POST /integrations/meta/attention/checkcan confirm it's done; a status Meta reports on the account clears with the next sync. adAccounts[].attention.clearsAtPublish- Only an ad Meta accepts shows it's done (confirming it's them, a pending step, a temporary block, restricted advertising, political ads):
POST /integrations/meta/attention/checkcan find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes. adAccounts[].attention.detail- Meta's own words.
adAccounts[].attention.line- One line under the title.
adAccounts[].attention.link- The Meta page to do it in:
label,labelCode(the label's stable code, such asmeta_link_open_meta),url. adAccounts[].attention.need- What Meta needs, e.g.
confirm_identity,audience_terms,policy_block,account_unpaid. adAccounts[].attention.next- What to do, in one sentence.
adAccounts[].attention.profile- The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
adAccounts[].attention.profileActs- Only that profile can do it (confirming it's them, a pending step, two-factor).
adAccounts[].attention.reason- One short sentence for a change that failed because of it.
adAccounts[].attention.since- When Meta said so; null for the account's status.
adAccounts[].attention.title- A short title: "Confirm the identity in Meta".
adAccounts[].attention.who- Who acts, in one sentence: the Meta profile Pluto publishes with, by name when Meta said it. Whoever reads it may not be that person.
adAccounts[].business- The business (Business Manager) that owns the ad account:
id,name(null when Meta gives none); null when Meta reports no business. Tells same-name ad accounts apart. adAccounts[].capacity- How full the ad account is:
adsInUse(the ads Meta counts toward its cap, those not archived or deleted),adLimit(6,000, or 50,000 for a bulk account),bulk,limitSource(where Meta documents the caps) andreadAt(when the ads were counted); null until a sync counted them. Information only: Pluto never holds an account back for it. adAccounts[].country- The country of the ad account's business address (ISO 3166,
US), as Meta reports it; null when Meta reports none. A new ad set's locations start with it. adAccounts[].currency- ISO 4217; the account's amounts are in it.
adAccounts[].id- act_…
adAccounts[].name- Name.
adAccounts[].pageIds- Pages it may publish from.
adAccounts[].pixels- The ad account's pixels (datasets) as the last sync read them, by name; a new launch on an account with exactly one gets it as its pixel.
adAccounts[].pixels[].id- The pixel (dataset) ID, what a launch's
pixeltakes. adAccounts[].pixels[].name- Its name in Meta; null when it has none.
adAccounts[].spendingLimit- Meta's account spending limit and what was spent toward it; null until Meta reported it.
adAccounts[].spendingLimit.amount- The limit in the ad account currency; null when the account has none.
adAccounts[].spendingLimit.readAt- When Meta reported it.
adAccounts[].spendingLimit.spent- Spent toward the limit (in total when there's none).
adAccounts[].timezone- IANA time zone.
adAccountsOff- The other ad accounts Meta shares, turned off: not synced, counted or offered until
PUT /integrations/meta/ad-accounts/{id}/syncturns them on. A new ad account arrives here. adAccountsOff[].accountStatus- Meta's account status.
adAccountsOff[].business- The business (Business Manager) that owns the ad account:
id,name; null when Meta reports none. adAccountsOff[].country- The country of the ad account's business address (ISO 3166); null when Meta reports none.
adAccountsOff[].currency- ISO 4217.
adAccountsOff[].id- act_…
adAccountsOff[].name- Name.
adAccountsOff[].timezone- IANA time zone.
connectedAt- Connected.
lastSync- The latest sync job:
jobId,status,error,errorCodeanderrorParams(a registerederror's stable code and the values it names, absent for an error without one),finishedAt; null before the first. metaUser- The Meta user who connected:
id,name. missingPermission- The permission Meta said is missing (e.g.
ads_management), when it named one. missingPermissions- Permissions Pluto asks for that this connection wasn't granted (e.g.
pages_manage_engagement): what they power, like comment moderation, stays off until an admin reconnects Meta and grants them. Empty when complete. pages- The Pages that are on: offered wherever a Page is chosen.
pages[].id- Page ID.
pages[].instagram- Linked Instagram account:
id,username. pages[].name- Name.
pagesOff- The other Pages, turned off with
PUT /integrations/meta/pages/{id}/enabled: offered nowhere and their comments not read, while their leads (as long as their ads bring them) and the ads already live on them go on. A new Page arrives here. pagesOff[].id- Page ID.
pagesOff[].instagram- Linked Instagram account:
id,username. pagesOff[].name- Name.
reason- Why it needs reconnecting:
expired(the token is gone) orpermission(Meta no longer grants one); null otherwise.One ofexpired,permission scopes- Permissions Meta granted.
status- Status.One of
connected,reauthorize,disconnected statusReason- Why it needs attention.
syncedAt- Last completed sync.
tokenExpiresAt- When Meta's token expires (about 60 days after connecting; reconnecting renews it).
tokenExpiry- Where the token is in its life:
expiringwithin 7 days oftokenExpiresAt(admins get an Inbox notice and an email; reconnecting renews it),expiredafter it. Null without a connection or when Meta gave no expiry.One ofvalid,expiring,expired version- Version.
curl "$PLUTO_API/integrations/meta" \
-H "Authorization: Bearer $PLUTO_KEY"List an ad account's audiences
The ad account's custom and lookalike audiences, read from Meta now: size estimate (null when Meta can't estimate it), delivery and operation status, what a lookalike is built from, and whether housing, employment and financial ads may use it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad account's ID. |
subtype | string | Optional | Only this Meta subtype, e.g. CUSTOM or LOOKALIKE. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- The ad account.
items- Audiences.
items[].createdTimeitems[].deliveryStatus- Meta's status: code and description.
items[].deliveryStatus.codeitems[].deliveryStatus.descriptionitems[].description- Description.
items[].id- Meta audience ID.
items[].kind- What it is.One of
custom,lookalike,other items[].lookalike- Lookalikes: what they're built from.
items[].lookalike.countryitems[].lookalike.originAudienceIdsitems[].lookalike.ratio- Share of the country, e.g. 0.01 for 1 %.
items[].name- Name.
items[].operationStatus- Meta's status: code and description.
items[].operationStatus.codeitems[].operationStatus.descriptionitems[].size- Meta's size estimate; null when Meta can't estimate it (never 0 for unknown).
items[].size.loweritems[].size.upperitems[].specialAdCategoryAllowed- Usable in housing, employment and financial ads (lookalikes aren't).
items[].subtype- Meta's subtype: CUSTOM, LOOKALIKE, WEBSITE, ENGAGEMENT, …
items[].updatedTime
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The Meta connection needs attention (
reason). - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/integrations/meta/ad-accounts/act_741877585619437/audiences" \
-H "Authorization: Bearer $PLUTO_KEY"Get minimum budget
Meta's minimum daily budget for an ad set of this ad account, in its currency, read from Meta now. A campaign budget spreads across its ad sets, so it needs at least this for each.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad account's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- The ad account.
currency- The ad account's currency (ISO 4217).
daily- The minimum daily budget per ad set, a decimal string in
currency; null when Meta gives none.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The Meta connection needs attention (
reason). - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/integrations/meta/ad-accounts/act_741877585619437/minimum-budget" \
-H "Authorization: Bearer $PLUTO_KEY"Set an ad account's Pages
Pages an ad account may publish from.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad account's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
pageIds- At least one.
Response
adAccountId- Account.
pageIds- Pages.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/integrations/meta/ad-accounts/act_741877585619437/pages" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8313a165-23c4-4bbe-bbb5-a3b2e9ad9bbe" \
-H "Content-Type: application/json" \
-d '{
"pageIds": [
"229657833239852"
]
}'Set an ad account's spending limit
Meta's account spending limit (spend_cap): when the ad account has spent this amount, Meta stops every ad in it, whatever any budget says. A new limit counts spend from the moment it's set. amount is a decimal string in the ad account currency; null removes the limit (the field is required, so an empty body never removes one). Queues one job and returns it: the job reads Meta first, writes only when the limit differs, reads it back and stores what Meta reports (spendingLimit on the ad account in GET /integrations/meta). One change per ad account at a time: another one while it runs is a 409. Needs publish as well as admin, and the ads_management permission in Meta.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad account's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
amount- The spending limit in the ad account currency, e.g.
5000.00;nullremoves it.
Response
adAccountId- The ad account.
amount- The limit asked for;
nullwhen it's removed. currency- The ad account currency (ISO 4217).
current- The limit as Meta last reported it, before this change;
nullwhen Meta hasn't reported it yet. current.amount- The limit in the ad account currency; null when the account has none.
current.readAt- When Meta reported it.
current.spent- Spent toward the limit (in total when there's none).
jobId- The job applying it; follow it with
GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/integrations/meta/ad-accounts/act_741877585619437/spending-limit" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d45d02c9-1c35-45cf-bac6-4088a2d7c0ed" \
-H "Content-Type: application/json" \
-d '{
"amount": "150.00"
}'Switch an ad account
Meta shares every ad account the person who connected can reach, and each one arrives off (adAccountsOff in GET /integrations/meta): 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 with their history, and jobId is that sync (null while Meta 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, comments) stays, read-only, and turning it on again goes on from there. Setting the state it already has changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad account's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
enabledtrueturns it on,falseoff.
Response
adAccountId- Account.
enabled- Whether it's on now.
jobId- The sync that brings it in, when this turned it on.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/integrations/meta/ad-accounts/act_741877585619437/sync" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e43525bb-355f-4b1e-bcc0-93014c18a054" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'Search targeting options
Search interests, behaviors and demographics.
Meta's detailed targeting options matching q, read from Meta now: ID, type (interests, behaviors, life_events, industries, income, family_statuses, work_positions, work_employers, education_schools, education_majors), taxonomy path, description and size estimate (null when Meta gives none). With specialAdCategory Meta returns only options allowed in that category; targetable says whether a targeting change takes it there. Meta's search isn't exhaustive. Use id and type in detailedTargeting.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad account's ID. |
q | string | Optional | What to look for (1-100 characters). |
type | string | Optional | Only this kind. |
specialAdCategory | string | Optional | Only options Meta allows in this special ad category, e.g. HOUSING. |
limit | string | Optional | Results, 1-100 (default 25). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- The ad account.
items- Matches, as Meta ranks them (not exhaustive).
items[].categoryinterest,behaviourordemographic.items[].description- Meta's description.
items[].id- Meta's ID: use it with
typein set_targeting's detailedTargeting. items[].name- Name.
items[].path- Where it sits in Meta's taxonomy, broadest first.
items[].size- Meta's audience size estimate
{lower, upper}; null when Meta gives none. items[].targetable- set_targeting takes it (in the special ad category searched for, if any).
items[].type- interests, behaviors, life_events, industries, income, family_statuses, work_positions, work_employers, education_schools or education_majors.
query- What was searched for.
specialAdCategory- The special ad category results are limited to.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The Meta connection needs attention (
reason). - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/integrations/meta/ad-accounts/act_741877585619437/targeting-search" \
-H "Authorization: Bearer $PLUTO_KEY"List synced ad sets
Synced ad sets (read-only structure).
Ad sets as the Meta sync last read them, keyset-paged by Meta ID. Budgets are decimal strings in currency; null means Meta reported none, never zero. launchId names the Pluto launch that manages the ad set, if any.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
adAccountId | string | Optional | act_… (optional). |
campaignId | string | Optional | Only this campaign's ad sets. |
search | string | Optional | Part of the name (case-insensitive) or the exact Meta ID. |
status | string | Optional | Only this effective status (effective_status, else status), e.g. ACTIVE; filtered before paging. |
after | string | Optional | Cursor. |
limit | string | Optional | Page size (1-500, default 200). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].adAccountId- act_…
items[].adAccountName- The ad account's name.
items[].ageDays- Whole days since createdTime (0 on the first day).
items[].automaticPlacements- Whether Meta chooses the placements (Advantage+ placements).
items[].bidStrategy- Bid strategy.
items[].campaignId- Meta campaign ID.
items[].campaignName- The campaign's name, when synced.
items[].changesBlocked- Why Meta's API can't change it (a legacy Advantage+ shopping or app campaign, or something in one); null when it can.
items[].createdTime- When it was created in Meta; null until the sync has read it.
items[].currency- ISO 4217.
items[].dailyBudget- In
currency; null when Meta reported none, never zero. items[].deliveryIssues- Issues Meta reports that keep it from delivering; [] when there are none, null until read.
items[].deliveryIssues[].errorCode- Meta's error code.
items[].deliveryIssues[].errorMessage- Meta's message.
items[].deliveryIssues[].errorSummary- Meta's short summary.
items[].deliveryIssues[].errorType- HARD_ERROR (stops delivery) or SOFT_ERROR for ads; Meta doesn't publish the values for campaigns and ad sets.
items[].deliveryIssues[].level- Where Meta places the issue (campaign, ad set or ad).
items[].effectiveStatus- Effective status.
items[].endTime- Delivery end.
items[].hasDeliveryIssue- Whether Meta reports a delivery issue.
items[].id- Meta ad set ID.
items[].launchId- The Pluto launch that manages it, if any.
items[].learning- The learning stage: status, conversions (in the learning phase; 0 once out), lastSignificantEditAt (the edit that restarted learning), attributionWindows.
items[].learningStatus- Meta's learning phase: LEARNING, SUCCESS (out of learning) or FAIL (learning limited). Null when Meta reports no learning stage (e.g. not delivering).One of
LEARNING,SUCCESS,FAIL items[].lifetimeBudget- In
currency; null when Meta reported none, never zero. items[].name- Name.
items[].placements- Placements: automatic (Meta chooses: no platform set), publisherPlatforms, facebookPositions, instagramPositions, audienceNetworkPositions, messengerPositions, threadsPositions, devicePlatforms. An empty list means Meta considers every default position for it.
items[].publisherPlatforms- The platforms chosen; [] when Meta chooses (automaticPlacements).
items[].smartPromotionType- The campaign's smart_promotion_type: GUIDED_CREATION, or AUTOMATED_SHOPPING_ADS / SMART_APP_PROMOTION for legacy Advantage+ shopping and app campaigns. Null until read.
items[].specialAdCategories- The campaign's special ad categories; [] when it declares none.
items[].startTime- Delivery start.
items[].status- Configured status.
items[].updatedTime- When it last changed in Meta.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/integrations/meta/ad-sets" \
-H "Authorization: Bearer $PLUTO_KEY"Archive a Meta ad set
As Ads Manager's Archive: sets the ad set (and so its ads) to archived in Meta and reads it back; Meta then lets it only be deleted, so it can't run again, and its results stay. It then leaves the synced lists; a launch's ad set is archived in the launch.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- Only for a launch's ad set: the draft version reviewed.
Response
deletes- What is deleted in Meta.
jobId- The job deleting in Meta.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 9b0fe776-ffe2-482a-b544-362dc4f20286" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Change a Meta ad set's bid
Follows Meta's rules per bid strategy: a bid cap or cost per result goal takes bidAmount; a ROAS goal takes roasGoal; highest volume takes neither. With a campaign budget the campaign holds the strategy, so bidStrategy is a 409.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
bidAmount- The amount the ad set's bidding strategy takes, in the ad account currency: on Meta the bid cap or cost per result goal (with COST_CAP and LOWEST_COST_WITH_BID_CAP).
bidStrategy- Optional, Meta only: switch the bid strategy too (ad sets with their own budget, not in a launch). Highest volume, cost per result goal, bid cap or ROAS goal.One of
LOWEST_COST_WITHOUT_CAP,COST_CAP,LOWEST_COST_WITH_BID_CAP,LOWEST_COST_WITH_MIN_ROAS roasGoal- Meta's ROAS goal, e.g. "2.5": at most four decimals, 0.01 to 1000 (with LOWEST_COST_WITH_MIN_ROAS).
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobId- The job applying the change; follow it with GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/bid" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 3acc7466-b81c-4c6e-a700-96f170bd0835" \
-H "Content-Type: application/json" \
-d '{
"bidAmount": "25.00",
"bidStrategy": "LOWEST_COST_WITHOUT_CAP",
"roasGoal": "150.00"
}'Change a Meta ad set's budget
An ad set with its own budget; one that uses the campaign budget is a 409. Meta allows 4 budget changes per ad set per hour: availableAt says when this one runs.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
amount- The new budget in the ad account currency; the budget keeps its period (daily, lifetime or total).
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobId- The job applying the change; follow it with GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/budget" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 1e4191ef-ae11-40ec-a735-c813474d5245" \
-H "Content-Type: application/json" \
-d '{
"amount": "150.00"
}'Duplicate a Meta ad set
Copies the ad set (deepCopy: with its ads), into its campaign or intoCampaignId, paused unless statusOption says otherwise.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
deepCopy- Ad sets and campaigns: copy what is inside too (default false).
endTime- Ad sets and campaigns: when the copied ad sets end.
intoAdSetId- Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignId- Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsrenameOptions.prefix- Put before the name.
renameOptions.strategy- Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of
ONLY_TOP_LEVEL_RENAME,DEEP_RENAME,NO_RENAME renameOptions.suffix- Put after the name (Meta's default is a localized " - Copy").
startTime- Ad sets and campaigns: when the copied ad sets start.
statusOption- How the copy starts (default PAUSED).One of
PAUSED,ACTIVE,INHERITED_FROM_SOURCE
Response
jobId- The copy job; its items name each copy (
output.copiedId). level- What is copied.One of
campaign,ad_set,ad objects- How many objects the job copies.
sourceId- The original's ID on its platform.
statusOption- How the copies start.One of
PAUSED,ACTIVE,INHERITED_FROM_SOURCE
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/copies" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 6619d87c-9cf5-4b57-af0c-6245427c8870" \
-H "Content-Type: application/json" \
-d '{
"deepCopy": true,
"endTime": "2026-09-30T13:00:00Z",
"intoAdSetId": "120240541407845332",
"intoCampaignId": "120227168091908311",
"renameOptions": {
"prefix": "Fall - ",
"strategy": "ONLY_TOP_LEVEL_RENAME",
"suffix": " - Copy"
},
"startTime": "2026-09-30T13:00:00Z",
"statusOption": "PAUSED"
}'Delete a Meta ad set
Irreversible: sets the ad set (and so its ads) to deleted in Meta and reads it back; it then leaves the synced lists. A launch's ad set goes through POST /ad-sets/{id}/meta-delete. Pausing is the reversible alternative.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- Only for a launch's ad set: the draft version reviewed.
Response
deletes- What is deleted in Meta.
jobId- The job deleting in Meta.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f1d7f271-1e9c-40d0-86d3-e6d366b34bd0" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Change a Meta ad set's schedule
Change an ad set's dates or ad scheduling in Meta.
Moves the start or end, or sets ad scheduling (day parts on the hour, at least an hour long; needs a lifetime budget).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
endTime- When it stops; in the future and after the start.
schedule- Meta's ad scheduling: the hours the ad set delivers. Needs a lifetime budget (the ad set's or its campaign's); an empty list turns it off.
schedule[].days- 0 is Sunday … 6 is Saturday.
schedule[].endMinute- Minute of the day it ends, on the hour, at least an hour later (up to 1440).
schedule[].startMinute- Minute of the day it starts, on the hour (0, 60, … 1380).
scheduleTimezone- Meta's ad scheduling: whose time zone the schedule follows (default
viewer).One ofviewer,account startTime- When the ad set starts delivering.
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobId- The job applying the change; follow it with GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/schedule" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: cdc570bc-d5ff-4eb8-b4e2-130ac19479cf" \
-H "Content-Type: application/json" \
-d '{
"endTime": "2026-09-30T13:00:00Z",
"schedule": [
{
"days": [
3
],
"endMinute": 3,
"startMinute": 3
}
],
"scheduleTimezone": "viewer",
"startTime": "2026-09-30T13:00:00Z"
}'Pause or activate a Meta ad set
The {id} is the Meta ID of a synced object (GET /integrations/meta/campaigns|ad-sets|ads), including ones created in Meta Ads Manager. An object a launch manages changes through the launch, exactly like its launch route. Answers 202 with the job; the change is read back from Meta into the synced lists as soon as it applies.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
status- Delivery.One of
ACTIVE,PAUSED
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobId- The job applying the change; follow it with GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/status" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 71f9c31c-dbdd-422f-b5af-e45dd1c6d847" \
-H "Content-Type: application/json" \
-d '{
"status": "ACTIVE"
}'Change a Meta ad set's targeting
Changes the targeting of a synced Meta ad set by its Meta ID (from GET /integrations/meta/ad-sets), also one created in Ads Manager: locations (countries, regions, cities with a radius, postal codes), excluded locations, age, gender, placements and audiences. Targeting the change doesn't name stays as it is in Meta. The job reads the ad set and its campaign's special ad categories again right before writing, checks the change again and reads it back. An ad set a launch manages goes through that launch, like PATCH /ad-sets/{id}/targeting.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad set's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
beneficiary- The EU advertiser: who benefits from the ads (with
payer). Needed when the ad set reaches the EU and neither it nor its ad account has one. customAudiences- Custom or lookalike audiences to reach; replaces the list (
[]removes them). detailedExclusions- Only
[], which removes the ad set's detailed targeting exclusions: Meta takes no new ones since Marketing API v22.0 (all versions from 2025-04-21). Exclude custom audiences with excludedAudiences. detailedExclusions[].id- Meta's ID (from search_targeting).
detailedExclusions[].name- Its name (optional, for people reading the change).
detailedExclusions[].type- The kind, as search_targeting returns it.One of
interests,behaviors,life_events,industries,income,family_statuses,work_positions,work_employers,education_schools,education_majors detailedTargeting- Interests, behaviors and demographics (IDs and
typefrom search_targeting) as groups: people must match every group, so each further group narrows the audience. Up to 25 groups of up to 1,000 items. Replaces the live detailed targeting;[]removes it. Ad sets a launch manages take one group of interests. Housing, employment and financial ads take only interests from Meta's approved list. excludedAudiences- Audiences to exclude; replaces the list.
excludedLocations- Where they don't run; replaces the excluded locations (
{}removes them). excludedLocations.cities- Cities, optionally with a radius.
excludedLocations.cities[].distanceUnit- Unit of
radius.One ofmile,kilometer excludedLocations.cities[].key- Meta's city key.
excludedLocations.cities[].radius- Around the city: 10-50 miles or 17-80 kilometers.
excludedLocations.countries- Countries, e.g. ["US", "DK"].
excludedLocations.regions- Regions (states, provinces), up to 200.
excludedLocations.regions[].key- Meta's location key (from Meta's targeting search).
excludedLocations.zips- Postal codes (e.g.
US:94304). excludedLocations.zips[].key- Meta's location key (from Meta's targeting search).
gender- Who by gender.One of
All,Men,Women locations- Where the ads run; replaces every live location. On an ad set a launch manages, use countries here; its regions, cities, postal codes and pins are edit_ad_sets
places, published with the launch. locations.cities- Cities, optionally with a radius.
locations.cities[].distanceUnit- Unit of
radius.One ofmile,kilometer locations.cities[].key- Meta's city key.
locations.cities[].radius- Around the city: 10-50 miles or 17-80 kilometers.
locations.countries- Countries, e.g. ["US", "DK"].
locations.regions- Regions (states, provinces), up to 200.
locations.regions[].key- Meta's location key (from Meta's targeting search).
locations.zips- Postal codes (e.g.
US:94304). locations.zips[].key- Meta's location key (from Meta's targeting search).
maxAge- 13-65 (65 means 65+).
minAge- 13-65.
payer- Who pays for the ads (with
beneficiary), for ads that reach the EU. placementsplacements.advantage- Advantage+ placements: Meta chooses (leave platforms out).
placements.platforms- Manual placements: the platforms.
placements.positions- Positions of the chosen platforms; left out means all of them.
Response
adSetId- The Pluto ad set, when a launch manages it.
appliedThroughdraft: through the launch that manages the ad set;meta: on Meta's own targeting spec.One ofdraft,metaavailableAt- When it runs.
fields- The targeting fields the change names.
jobId- The job making the change in Meta; follow it with wait_for_job.
metaAdSetId- Meta's ad set ID.
specialAdCategories- The campaign's special ad categories the change was checked against.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The Meta connection needs attention (
reason), Meta refused the read, or the change makes the ad set reach the EU without the advertiser names Meta requires there, on the change, the ad set or its ad account's defaults (reason: eu_advertiser_required,missing, andfix: Meta Ads Manager on the ad set; sendbeneficiaryandpayerwith the change instead). - 422Meta's special ad category rules are enforced before anything is queued: housing, employment and financial products and services ads keep ages 18-65+ and all genders, take no excluded locations, postal codes or small areas, need city radii of at least 15 miles (25 km; 15 km in Europe) and can't use lookalike audiences (Meta retired Special Ad Audiences in 2022, so nothing converts them); social issue, electoral and political ads can't add EU countries. Housing, employment and financial ads also take only interests (Meta's approved list), no behaviors, demographics or detailed exclusions. A refusal is a
422naming the field. New detailed targeting exclusions are refused for every ad set (Meta stopped taking them in Marketing API v22.0);detailedExclusions: []removes existing ones. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/integrations/meta/ad-sets/120240541407845332/targeting" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 18b973c3-e663-498c-b2e1-45f269f9f9a5" \
-H "Content-Type: application/json" \
-d '{
"beneficiary": "Brevanne, Inc.",
"customAudiences": [
"Brevanne"
],
"detailedExclusions": [
{
"id": "1663c055-be5e-43a9-b231-83903ab9bbfa",
"name": "Vitamin C Serum, UGC 9x16",
"type": "interests"
}
],
"detailedTargeting": [
[
{
"id": "1663c055-be5e-43a9-b231-83903ab9bbfa",
"name": "Vitamin C Serum, UGC 9x16",
"type": "interests"
}
]
],
"excludedAudiences": [
"Brevanne"
],
"excludedLocations": {
"cities": [
{
"distanceUnit": "mile",
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA",
"radius": 3
}
],
"countries": [
"US"
],
"regions": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
],
"zips": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
]
},
"gender": "All",
"locations": {
"cities": [
{
"distanceUnit": "mile",
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA",
"radius": 3
}
],
"countries": [
"US"
],
"regions": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
],
"zips": [
{
"key": "sk_4DaFQUdZAQUoVFVoIc2AcLHjwqgEt0ZA"
}
]
},
"maxAge": 3,
"minAge": 3,
"payer": "Brevanne, Inc.",
"placements": {
"advantage": true,
"platforms": [
"facebook"
],
"positions": [
"platform.position"
]
}
}'List synced ads
Synced ads (read-only structure).
Ads as the Meta sync last read them, keyset-paged by Meta ID, with the creative ID and a Meta-hosted thumbnail link (never copied into Pluto's storage by the sync).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
adAccountId | string | Optional | act_… (optional). |
campaignId | string | Optional | Only this campaign's ads. |
adSetId | string | Optional | Only this ad set's ads. |
search | string | Optional | Part of the name (case-insensitive) or the exact Meta ID. |
status | string | Optional | Only this effective status (effective_status, else status), e.g. ACTIVE; filtered before paging. |
after | string | Optional | Cursor. |
limit | string | Optional | Page size (1-500, default 200). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].adAccountId- act_…
items[].adAccountName- The ad account's name.
items[].adSetId- Meta ad set ID.
items[].ageDays- Whole days since createdTime (0 on the first day).
items[].automaticPlacements- Whether Meta chooses the placements (Advantage+ placements).
items[].campaignId- Meta campaign ID.
items[].changesBlocked- Why Meta's API can't change it (a legacy Advantage+ shopping or app campaign, or something in one); null when it can.
items[].createdTime- When it was created in Meta; null until the sync has read it.
items[].creativeId- Meta creative ID.
items[].creativeType- The creative's type as Meta reports it (
object_type).One ofAPPLICATION,DOMAIN,EVENT,INVALID,PAGE,PHOTO,POST_DELETED,PRIVACY_CHECK_FAIL,SHARE,STATUS,STORE_ITEM,VIDEO items[].deliveryIssues- Issues Meta reports that keep it from delivering; [] when there are none, null until read.
items[].deliveryIssues[].errorCode- Meta's error code.
items[].deliveryIssues[].errorMessage- Meta's message.
items[].deliveryIssues[].errorSummary- Meta's short summary.
items[].deliveryIssues[].errorType- HARD_ERROR (stops delivery) or SOFT_ERROR for ads; Meta doesn't publish the values for campaigns and ad sets.
items[].deliveryIssues[].level- Where Meta places the issue (campaign, ad set or ad).
items[].effectiveStatus- Effective status.
items[].hasDeliveryIssue- Whether Meta reports a delivery issue.
items[].id- Meta ad ID.
items[].launchId- The Pluto launch that manages it, if any.
items[].learning- The learning stage: status, conversions (in the learning phase; 0 once out), lastSignificantEditAt (the edit that restarted learning), attributionWindows.
items[].learningStatus- Meta's learning phase: LEARNING, SUCCESS (out of learning) or FAIL (learning limited). Null when Meta reports no learning stage (e.g. not delivering).One of
LEARNING,SUCCESS,FAIL items[].name- Name.
items[].placements- Placements: automatic (Meta chooses: no platform set), publisherPlatforms, facebookPositions, instagramPositions, audienceNetworkPositions, messengerPositions, threadsPositions, devicePlatforms. An empty list means Meta considers every default position for it.
items[].publisherPlatforms- The platforms chosen; [] when Meta chooses (automaticPlacements).
items[].smartPromotionType- The campaign's smart_promotion_type: GUIDED_CREATION, or AUTOMATED_SHOPPING_ADS / SMART_APP_PROMOTION for legacy Advantage+ shopping and app campaigns. Null until read.
items[].specialAdCategories- The campaign's special ad categories; [] when it declares none.
items[].status- Configured status.
items[].thumbnailUrl- Meta-hosted preview image link.
items[].updatedTime- When it last changed in Meta.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/integrations/meta/ads" \
-H "Authorization: Bearer $PLUTO_KEY"Archive a Meta ad
As Ads Manager's Archive: sets the ad to archived in Meta and reads it back; Meta then lets it only be deleted, so it can't run again, and its results stay. It then leaves the synced lists.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- Only for a launch's ad: the draft version reviewed.
Response
deletes- What is deleted in Meta.
jobId- The job deleting in Meta.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ads/120288304425086360/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 0292ecf9-1204-4d81-ac60-dc11fee151e5" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Duplicate a Meta ad
Copies the ad into its ad set or intoAdSetId, paused unless statusOption says otherwise.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
deepCopy- Ad sets and campaigns: copy what is inside too (default false).
endTime- Ad sets and campaigns: when the copied ad sets end.
intoAdSetId- Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignId- Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsrenameOptions.prefix- Put before the name.
renameOptions.strategy- Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of
ONLY_TOP_LEVEL_RENAME,DEEP_RENAME,NO_RENAME renameOptions.suffix- Put after the name (Meta's default is a localized " - Copy").
startTime- Ad sets and campaigns: when the copied ad sets start.
statusOption- How the copy starts (default PAUSED).One of
PAUSED,ACTIVE,INHERITED_FROM_SOURCE
Response
jobId- The copy job; its items name each copy (
output.copiedId). level- What is copied.One of
campaign,ad_set,ad objects- How many objects the job copies.
sourceId- The original's ID on its platform.
statusOption- How the copies start.One of
PAUSED,ACTIVE,INHERITED_FROM_SOURCE
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ads/120288304425086360/copies" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: aa238861-92cb-49d7-af68-9b42ffba3654" \
-H "Content-Type: application/json" \
-d '{
"deepCopy": true,
"endTime": "2026-09-30T13:00:00Z",
"intoAdSetId": "120240541407845332",
"intoCampaignId": "120227168091908311",
"renameOptions": {
"prefix": "Fall - ",
"strategy": "ONLY_TOP_LEVEL_RENAME",
"suffix": " - Copy"
},
"startTime": "2026-09-30T13:00:00Z",
"statusOption": "PAUSED"
}'Delete a Meta ad
Irreversible: deletes the ad in Meta and reads it back; it then leaves the synced lists.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- Only for a launch's ad: the draft version reviewed.
Response
deletes- What is deleted in Meta.
jobId- The job deleting in Meta.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ads/120288304425086360/delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b2e43af7-7854-4dea-b2ac-bf11b0c1e8a1" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Pause or activate a Meta ad
The {id} is the Meta ID of a synced object (GET /integrations/meta/campaigns|ad-sets|ads), including ones created in Meta Ads Manager. An object a launch manages changes through the launch, exactly like its launch route. Answers 202 with the job; the change is read back from Meta into the synced lists as soon as it applies.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
status- Delivery.One of
ACTIVE,PAUSED
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobId- The job applying the change; follow it with GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/ads/120288304425086360/status" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d127fd0b-0961-41c3-86df-6946b0b6cf1a" \
-H "Content-Type: application/json" \
-d '{
"status": "ACTIVE"
}'Get what a model sees of a Meta ad
An ad by its Meta ID. One Pluto published is answered as its launch's ad; an ad that exists only in Meta has its creative (image, or a video's frames) and copy read from Meta the first time, within Meta's rate limits, and kept. note says when Meta isn't connected or the creative couldn't be read yet.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta ad's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- The ad account's ID on its platform (act_… on Meta).
adSetId- Ad set.
aspectRatio- As ad specs name it.
copy- The copy it runs with: primaryText, headline, description, callToAction, url; a launch ad adds its variations (primaryTexts, headlines, descriptions).
durationMs- Videos: duration.
effectiveStatus- Delivery in Meta when it's live there.
expiresAt- When the still URLs stop working.
formatimage,videooraudio(an audio ad, where the platform has them).hasAudio- Videos: whether there is a sound track.
id- The Pluto ad ID, or the Meta ad ID.
launchId- Launch.
media- A launch ad's creative.
media.archivedAt- Archived; still counted toward media storage until deleted.
media.byteSize- Size in bytes.
media.contentType- MIME type.
media.createdAt- Added.
media.createdBy- Their ID.
media.createdByKind- Who added it.One of
person,api_key,agent,system media.deletedAt- Deleted by a person: the files are gone and no longer counted.
media.durationMs- Videos and audio files: duration.
media.error- Why processing failed.
media.errorCode- A registered
error's stable code (such asmedia_image_unreadable), for an app to say it in its language; absent for an error without one. media.errorParams- The values
errorCode's sentence names, present exactly when it is. media.folderId- Folder; null for the library root.
media.hasPreview- A preview image exists: an image's thumbnail or a video's poster frame.
media.height- Pixels, once processed.
media.id- ID.
media.kind- Kind: a
documentis a PDF for document ads, in workspaces that run them;audioan MP3, OGG or WAV for audio ads, where a platform has them.One ofimage,video,document,audio media.name- Name.
media.pageCount- Documents: pages, once processed.
media.processedAt- Processed.
media.sha256- Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatform- The ad platform it came from:
metawhen Keep in sync or Import from Meta brought it; null for files people added. media.sourceUrl- Where an import came from.
media.status- Upload/processing status; only
readymedia publishes.One ofuploading,processing,ready,failed media.updatedAt- Last change.
media.version- Increments on every change; send as
expectedVersion. media.warnings- Provider-spec findings that don't block use.
media.warnings[].coderesolution,aspect_ratio,format,duration,dimensions_unknown,duration_unknown; videos alsoplacement_feed,placement_stories_reels,placement_in_stream,placement_reels,placement_instagram(a placement that crops or skips it) andposter_unavailable(Meta's own thumbnail is used).media.warnings[].message- Finding.
media.warnings[].messageCode- A registered
message's stable code (such asmedia_placement_feed), for an app to say it in its language. media.warnings[].messageParams- The values
messageCode's sentence names, present exactly when it is. media.width- Pixels, once processed.
metaAdId- The ad in Meta, once published there.
name- Name.
note- Why there's nothing (or less) to look at.
sourcelaunch: an ad of a Pluto launch (draft or published);meta: an ad that exists only in Meta.One oflaunch,metastills- In order: one for an image, up to 8 frames for a video.
stills[].at- Videos: the same as a timestamp, e.g.
0:04. stills[].atMs- Videos: where the frame is (ms).
stills[].height- Pixels.
stills[].url- Short-lived URL of the JPEG.
stills[].width- Pixels.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/integrations/meta/ads/120288304425086360/view" \
-H "Authorization: Bearer $PLUTO_KEY"List open Meta steps
Ad accounts and Pages where Meta needs a person to do something in Meta before it takes more changes (confirm it's them, accept terms, pay a balance, a policy block), blocking first. Changes in them fail at once with the same reason until it is done; reconnecting Meta doesn't clear it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
data- Open needs.
data[].attentiondata[].attention.blocking- Whether it stops changes (a review or an overdue payment doesn't yet).
data[].attention.checkable- Whether
POST /integrations/meta/attention/checkcan confirm it's done; a status Meta reports on the account clears with the next sync. data[].attention.clearsAtPublish- Only an ad Meta accepts shows it's done (confirming it's them, a pending step, a temporary block, restricted advertising, political ads):
POST /integrations/meta/attention/checkcan find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes. data[].attention.detail- Meta's own words.
data[].attention.line- One line under the title.
data[].attention.link- The Meta page to do it in:
label,labelCode(the label's stable code, such asmeta_link_open_meta),url. data[].attention.need- What Meta needs, e.g.
confirm_identity,audience_terms,policy_block,account_unpaid. data[].attention.next- What to do, in one sentence.
data[].attention.profile- The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
data[].attention.profileActs- Only that profile can do it (confirming it's them, a pending step, two-factor).
data[].attention.reason- One short sentence for a change that failed because of it.
data[].attention.since- When Meta said so; null for the account's status.
data[].attention.title- A short title: "Confirm the identity in Meta".
data[].attention.who- Who acts, in one sentence: the Meta profile Pluto publishes with, by name when Meta said it. Whoever reads it may not be that person.
data[].id- The ad account (
act_…) or Page ID. data[].name- Name.
data[].object- What needs it.One of
ad_account,page
curl "$PLUTO_API/integrations/meta/attention" \
-H "Authorization: Bearer $PLUTO_KEY"Check a Meta step is done
"I've done it": asks Meta whether it takes changes in the ad account again, with a dry run that changes nothing, and clears the need when it does. A Page's need clears when asked. Pluto also checks by itself every few minutes while a need is open.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
id- The ad account (
act_…) or Page ID. object- What to check.One of
ad_account,page
Response
atNextPublish- Meta took the check, but only an ad Meta accepts shows this need is done: it stays open, and Pluto will know at the next publish.
attention- What is still needed; null when nothing.
attention.blocking- Whether it stops changes (a review or an overdue payment doesn't yet).
attention.checkable- Whether
POST /integrations/meta/attention/checkcan confirm it's done; a status Meta reports on the account clears with the next sync. attention.clearsAtPublish- Only an ad Meta accepts shows it's done (confirming it's them, a pending step, a temporary block, restricted advertising, political ads):
POST /integrations/meta/attention/checkcan find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes. attention.detail- Meta's own words.
attention.line- One line under the title.
attention.link- The Meta page to do it in:
label,labelCode(the label's stable code, such asmeta_link_open_meta),url. attention.need- What Meta needs, e.g.
confirm_identity,audience_terms,policy_block,account_unpaid. attention.next- What to do, in one sentence.
attention.profile- The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
attention.profileActs- Only that profile can do it (confirming it's them, a pending step, two-factor).
attention.reason- One short sentence for a change that failed because of it.
attention.since- When Meta said so; null for the account's status.
attention.title- A short title: "Confirm the identity in Meta".
attention.who- Who acts, in one sentence: the Meta profile Pluto publishes with, by name when Meta said it. Whoever reads it may not be that person.
cleared- Meta takes changes again.
unknown- Why Meta couldn't be asked right now.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The ad account or Page isn't this workspace's.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/attention/check" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8728b3fd-ed4a-41db-bc62-cbe8d578561e" \
-H "Content-Type: application/json" \
-d '{
"id": "1663c055-be5e-43a9-b231-83903ab9bbfa",
"object": "ad_account"
}'List synced campaigns
Synced campaigns of an ad account.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
adAccountId | string | Optional | act_… |
status | string | Optional | Only this effective status (effective_status, else status), e.g. ACTIVE; filtered before paging. |
search | string | Optional | Part of the name (case-insensitive) or the exact Meta ID. |
after | string | Optional | Cursor. |
limit | string | Optional | Page size (1-500, default 200). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].adAccountId- act_…
items[].adAccountName- The ad account's name.
items[].ageDays- Whole days since createdTime (0 on the first day).
items[].bidStrategy- Bid strategy.
items[].budgetMode- Where the budget lives.One of
campaign,ad_set items[].changesBlocked- Why Meta's API can't change it (a legacy Advantage+ shopping or app campaign, or something in one); null when it can.
items[].createdTime- When it was created in Meta; null until the sync has read it.
items[].currency- ISO 4217.
items[].dailyBudget- In
currency; null when Meta reported none, never zero. items[].deliveryIssues- Issues Meta reports that keep it from delivering; [] when there are none, null until read.
items[].deliveryIssues[].errorCode- Meta's error code.
items[].deliveryIssues[].errorMessage- Meta's message.
items[].deliveryIssues[].errorSummary- Meta's short summary.
items[].deliveryIssues[].errorType- HARD_ERROR (stops delivery) or SOFT_ERROR for ads; Meta doesn't publish the values for campaigns and ad sets.
items[].deliveryIssues[].level- Where Meta places the issue (campaign, ad set or ad).
items[].effectiveStatus- Effective status.
items[].hasDeliveryIssue- Whether Meta reports a delivery issue.
items[].id- Campaign ID.
items[].lifetimeBudget- In
currency; null when Meta reported none, never zero. items[].name- Name.
items[].objective- Objective.
items[].smartPromotionType- The campaign's smart_promotion_type: GUIDED_CREATION, or AUTOMATED_SHOPPING_ADS / SMART_APP_PROMOTION for legacy Advantage+ shopping and app campaigns. Null until read.
items[].specialAdCategories- The campaign's special ad categories; [] when it declares none.
items[].status- Configured status.
items[].updatedTime- When it last changed in Meta (budget and spend cap edits don't move it).
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/integrations/meta/campaigns" \
-H "Authorization: Bearer $PLUTO_KEY"Archive a Meta campaign
As Ads Manager's Archive: sets the campaign (and so its ad sets and ads) to archived in Meta and reads it back; Meta then lets it only be deleted, so it can't run again, and its results stay. It then leaves the synced lists; a launch's campaign archives its ads and ad sets first and archives the launch.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta campaign's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- Only for a launch's campaign: the launch version reviewed.
Response
deletes- What is deleted in Meta.
jobId- The job deleting in Meta.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/campaigns/120227168091908311/archive" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f35cfbbf-8268-48d4-884f-ea12ff6c60bc" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Change a Meta campaign's budget
A campaign with a campaign budget (Advantage campaign budget); one with ad set budgets is a 409. The {id} is a Meta campaign ID; see POST /integrations/meta/campaigns/{id}/status.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta campaign's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
amount- The new budget in the ad account currency; the budget keeps its period (daily, lifetime or total).
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobId- The job applying the change; follow it with GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/integrations/meta/campaigns/120227168091908311/budget" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: fb62e22a-88af-4a7b-8dbd-c15cbe8b4985" \
-H "Content-Type: application/json" \
-d '{
"amount": "150.00"
}'Duplicate a Meta campaign
Copies the campaign (deepCopy: with its ad sets and ads), paused unless statusOption says otherwise. Meta copies up to 3 ads in one call; a larger campaign is copied level by level in the same job. Every copy is written into the synced lists as soon as it exists.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta campaign's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
deepCopy- Ad sets and campaigns: copy what is inside too (default false).
endTime- Ad sets and campaigns: when the copied ad sets end.
intoAdSetId- Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignId- Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsrenameOptions.prefix- Put before the name.
renameOptions.strategy- Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of
ONLY_TOP_LEVEL_RENAME,DEEP_RENAME,NO_RENAME renameOptions.suffix- Put after the name (Meta's default is a localized " - Copy").
startTime- Ad sets and campaigns: when the copied ad sets start.
statusOption- How the copy starts (default PAUSED).One of
PAUSED,ACTIVE,INHERITED_FROM_SOURCE
Response
jobId- The copy job; its items name each copy (
output.copiedId). level- What is copied.One of
campaign,ad_set,ad objects- How many objects the job copies.
sourceId- The original's ID on its platform.
statusOption- How the copies start.One of
PAUSED,ACTIVE,INHERITED_FROM_SOURCE
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/campaigns/120227168091908311/copies" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: b7e6d330-af25-487b-93d9-b9b502b123ab" \
-H "Content-Type: application/json" \
-d '{
"deepCopy": true,
"endTime": "2026-09-30T13:00:00Z",
"intoAdSetId": "120240541407845332",
"intoCampaignId": "120227168091908311",
"renameOptions": {
"prefix": "Fall - ",
"strategy": "ONLY_TOP_LEVEL_RENAME",
"suffix": " - Copy"
},
"startTime": "2026-09-30T13:00:00Z",
"statusOption": "PAUSED"
}'Delete a Meta campaign
Irreversible, as Ads Manager's Delete: sets the campaign (and so its ad sets and ads) to deleted in Meta and reads it back; it then leaves the synced lists. A launch's campaign goes through POST /launches/{id}/campaign/remove, which deletes its ads and ad sets first and archives the launch. Pausing is the reversible alternative.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta campaign's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
expectedVersion- Only for a launch's campaign: the launch version reviewed.
Response
deletes- What is deleted in Meta.
jobId- The job deleting in Meta.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/campaigns/120227168091908311/delete" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 57115d61-c63c-4204-ac85-6fd6804aa5b5" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Pause or activate a Meta campaign
The {id} is the Meta ID of a synced object (GET /integrations/meta/campaigns|ad-sets|ads), including ones created in Meta Ads Manager. An object a launch manages changes through the launch, exactly like its launch route. Answers 202 with the job; the change is read back from Meta into the synced lists as soon as it applies.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta campaign's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
status- Delivery.One of
ACTIVE,PAUSED
Response
availableAt- When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobId- The job applying the change; follow it with GET /jobs/{id}.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/campaigns/120227168091908311/status" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 681dffc2-5f32-416a-8058-fe39b408729d" \
-H "Content-Type: application/json" \
-d '{
"status": "ACTIVE"
}'Start connecting Meta
Returns a Facebook Login URL for a person to open in their browser; nothing connects until they approve in Meta. Give the URL to the person the credential acts for: they must be signed in to Pluto Ads as themselves when they open it, and the connection finishes when Facebook sends them back. The URL works once, for 15 minutes. reconnect: true signs in again for an existing connection (status reauthorize). Needs a credential that acts for a person (a connected agent or an mcp agent client; an API key gets 403). 409 when Meta is already connected (connect) or isn't (reconnect). The same command as MCP connect_meta and reconnect_meta.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
reconnect- Sign in again for an existing connection instead of connecting.
returnTo- Where the app opens after the login, a path such as
/integrations(the default).
Response
authorizationUrl- Facebook Login for the person to open in their browser (single use).
expiresAt- The URL stops working after this.
personId- The person who must open the URL, signed in to Pluto Ads.
status- The connection's status before the login.One of
connected,reauthorize,disconnected
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Meta is already connected, or isn't connected (reconnect).
- 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/connect" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 533d74fd-fb3a-437c-a15b-c4b8bbebc5e4" \
-H "Content-Type: application/json" \
-d '{
"reconnect": true,
"returnTo": "/settings/billing"
}'Disconnect Meta
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountLimit- Ad accounts the last sync didn't add because the plan connects no more (Pro and the trial: 3 Meta ad accounts per organization; the cap counts per platform):
message,details(the same as a402 plan_limitwithfeature: ad_accounts:feature,reasonplan_caportrial,limit,used,plan,nextAction,upgradeTo,upgradeUrl) andheldBack[{id, name}]. Accounts already connected always stay. Null when none are waiting; on a plan that takes them, the next sync adds them. adAccounts- The ad accounts that are on: synced, counted against the plan's cap and offered everywhere in Pluto.
adAccounts[].accountStatus- Meta's account status.
adAccounts[].attention- What Meta needs a person to do in Meta before this ad account takes more changes; null when nothing.
adAccounts[].attention.blocking- Whether it stops changes (a review or an overdue payment doesn't yet).
adAccounts[].attention.checkable- Whether
POST /integrations/meta/attention/checkcan confirm it's done; a status Meta reports on the account clears with the next sync. adAccounts[].attention.clearsAtPublish- Only an ad Meta accepts shows it's done (confirming it's them, a pending step, a temporary block, restricted advertising, political ads):
POST /integrations/meta/attention/checkcan find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes. adAccounts[].attention.detail- Meta's own words.
adAccounts[].attention.line- One line under the title.
adAccounts[].attention.link- The Meta page to do it in:
label,labelCode(the label's stable code, such asmeta_link_open_meta),url. adAccounts[].attention.need- What Meta needs, e.g.
confirm_identity,audience_terms,policy_block,account_unpaid. adAccounts[].attention.next- What to do, in one sentence.
adAccounts[].attention.profile- The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
adAccounts[].attention.profileActs- Only that profile can do it (confirming it's them, a pending step, two-factor).
adAccounts[].attention.reason- One short sentence for a change that failed because of it.
adAccounts[].attention.since- When Meta said so; null for the account's status.
adAccounts[].attention.title- A short title: "Confirm the identity in Meta".
adAccounts[].attention.who- Who acts, in one sentence: the Meta profile Pluto publishes with, by name when Meta said it. Whoever reads it may not be that person.
adAccounts[].business- The business (Business Manager) that owns the ad account:
id,name(null when Meta gives none); null when Meta reports no business. Tells same-name ad accounts apart. adAccounts[].capacity- How full the ad account is:
adsInUse(the ads Meta counts toward its cap, those not archived or deleted),adLimit(6,000, or 50,000 for a bulk account),bulk,limitSource(where Meta documents the caps) andreadAt(when the ads were counted); null until a sync counted them. Information only: Pluto never holds an account back for it. adAccounts[].country- The country of the ad account's business address (ISO 3166,
US), as Meta reports it; null when Meta reports none. A new ad set's locations start with it. adAccounts[].currency- ISO 4217; the account's amounts are in it.
adAccounts[].id- act_…
adAccounts[].name- Name.
adAccounts[].pageIds- Pages it may publish from.
adAccounts[].pixels- The ad account's pixels (datasets) as the last sync read them, by name; a new launch on an account with exactly one gets it as its pixel.
adAccounts[].pixels[].id- The pixel (dataset) ID, what a launch's
pixeltakes. adAccounts[].pixels[].name- Its name in Meta; null when it has none.
adAccounts[].spendingLimit- Meta's account spending limit and what was spent toward it; null until Meta reported it.
adAccounts[].spendingLimit.amount- The limit in the ad account currency; null when the account has none.
adAccounts[].spendingLimit.readAt- When Meta reported it.
adAccounts[].spendingLimit.spent- Spent toward the limit (in total when there's none).
adAccounts[].timezone- IANA time zone.
adAccountsOff- The other ad accounts Meta shares, turned off: not synced, counted or offered until
PUT /integrations/meta/ad-accounts/{id}/syncturns them on. A new ad account arrives here. adAccountsOff[].accountStatus- Meta's account status.
adAccountsOff[].business- The business (Business Manager) that owns the ad account:
id,name; null when Meta reports none. adAccountsOff[].country- The country of the ad account's business address (ISO 3166); null when Meta reports none.
adAccountsOff[].currency- ISO 4217.
adAccountsOff[].id- act_…
adAccountsOff[].name- Name.
adAccountsOff[].timezone- IANA time zone.
connectedAt- Connected.
lastSync- The latest sync job:
jobId,status,error,errorCodeanderrorParams(a registerederror's stable code and the values it names, absent for an error without one),finishedAt; null before the first. metaUser- The Meta user who connected:
id,name. missingPermission- The permission Meta said is missing (e.g.
ads_management), when it named one. missingPermissions- Permissions Pluto asks for that this connection wasn't granted (e.g.
pages_manage_engagement): what they power, like comment moderation, stays off until an admin reconnects Meta and grants them. Empty when complete. pages- The Pages that are on: offered wherever a Page is chosen.
pages[].id- Page ID.
pages[].instagram- Linked Instagram account:
id,username. pages[].name- Name.
pagesOff- The other Pages, turned off with
PUT /integrations/meta/pages/{id}/enabled: offered nowhere and their comments not read, while their leads (as long as their ads bring them) and the ads already live on them go on. A new Page arrives here. pagesOff[].id- Page ID.
pagesOff[].instagram- Linked Instagram account:
id,username. pagesOff[].name- Name.
reason- Why it needs reconnecting:
expired(the token is gone) orpermission(Meta no longer grants one); null otherwise.One ofexpired,permission scopes- Permissions Meta granted.
status- Status.One of
connected,reauthorize,disconnected statusReason- Why it needs attention.
syncedAt- Last completed sync.
tokenExpiresAt- When Meta's token expires (about 60 days after connecting; reconnecting renews it).
tokenExpiry- Where the token is in its life:
expiringwithin 7 days oftokenExpiresAt(admins get an Inbox notice and an email; reconnecting renews it),expiredafter it. Null without a connection or when Meta gave no expiry.One ofvalid,expiring,expired version- Version.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/disconnect" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 3f08512a-8b42-49c6-84f1-1a461646893c"Import campaigns or ad sets from Meta
Each pick becomes a launch linked to its live Meta objects, with the live version read back from Meta; values Pluto can't represent stay managed in Meta (read-only, never written back). Only the imported ads' images and videos are copied into the library (deduplicated by SHA-256). Importing the same pick again refreshes its launch (refused while it has pending changes). Returns the job; follow the report.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- act_…
adSetIds- Ad sets: each becomes one launch into its existing campaign.
campaignIds- Campaigns: each becomes one launch with all its ad sets and ads.
Response
items- One job item per pick.
items[].adSets- Current ad sets it brings along, as last synced.
items[].ads- Current ads it brings along, as last synced.
items[].campaignId- Ad sets: their campaign.
items[].effectiveStatus- Effective status.
items[].kind- What was picked.One of
campaign,adSet items[].launchId- An earlier import's launch: importing again refreshes it.
items[].linkedLaunchId- Another launch already manages it; it can't be imported.
items[].metaId- Meta ID.
items[].name- Name.
items[].status- Configured status.
jobId- The import job;
GET /integrations/meta/imports/{jobId}is its report.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/imports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 1a9aa52f-340d-4de9-ae50-9f5d9054bade" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"adSetIds": [
"120240541407845332"
],
"campaignIds": [
"120227168091908311"
]
}'Preview an import from Meta
What importing these campaigns or ad sets brings along (from the synced structure), which ones refresh an earlier import (launchId) and which another launch already manages (linkedLaunchId). Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- act_…
adSetIds- Ad sets: each becomes one launch into its existing campaign.
campaignIds- Campaigns: each becomes one launch with all its ad sets and ads.
Response
adAccountId- act_…
currency- ISO 4217.
items- The picks.
items[].adSets- Current ad sets it brings along, as last synced.
items[].ads- Current ads it brings along, as last synced.
items[].campaignId- Ad sets: their campaign.
items[].effectiveStatus- Effective status.
items[].kind- What was picked.One of
campaign,adSet items[].launchId- An earlier import's launch: importing again refreshes it.
items[].linkedLaunchId- Another launch already manages it; it can't be imported.
items[].metaId- Meta ID.
items[].name- Name.
items[].status- Configured status.
notes- What an import never does.
curl -X POST "$PLUTO_API/integrations/meta/imports/preview" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"adSetIds": [
"120240541407845332"
],
"campaignIds": [
"120227168091908311"
]
}'Get an import report
Per pick: its status and, once done, the launch, every ad set and ad that came along with what stays managed in Meta, what didn't come along and why, and how many files were copied or already in the library. Failed picks carry the reason.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta import's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- act_…
createdAt- Started.
failed- Failed.
finishedAt- Finished.
items- Picks.
jobId- The import job.
status- Job status.
succeeded- Imported.
total- Picks.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/integrations/meta/imports/66fcd829-9441-4321-acf8-1c666a8eb9c0" \
-H "Authorization: Bearer $PLUTO_KEY"Switch a Page
A new Page arrives off (pagesOff in GET /integrations/meta) and one already stored keeps its switch. On: offered wherever a Page is chosen (launches, ads, defaults, an ad account's Pages, loops, agents). Off: offered nowhere, so a workspace with many Pages keeps the list short, and a draft can't publish as it; Pluto stops reading its comments and reads its leads only while its ads still bring them (a lead in the last 30 days), an ad already live on it stays as it is, and the ad accounts it was chosen for keep it for when it's on again; turning it on reads its comments and leads again. It moves between pages and pagesOff in GET /integrations/meta. Setting the state it already has changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The Meta page's ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
enabledtrueturns it on,falseoff.
Response
enabled- Whether it's on now.
pageId- Page.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/integrations/meta/pages/65ed0584-aa3e-40e6-a062-786ca33d5821/enabled" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8f46eed8-1a78-4153-919f-ad0e4b08839a" \
-H "Content-Type: application/json" \
-d '{
"enabled": true
}'Sync from Meta
Sync ad accounts, Pages, campaigns, ad sets and ads.
Returns the queued (or already running) sync job of the same scope. The body is optional: without one it syncs every ad account, Page, campaign, ad set and ad, which takes minutes with many ad accounts. adAccountId syncs one ad account's campaigns, ad sets and ads; campaignId, adSetId or adId reads one synced object as Meta reports it now, with the ad sets and ads under it, in seconds. Give at most one (422 otherwise); 404 for an ID the sync doesn't have.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountId- Only this ad account (act_…).
adId- Only this synced ad.
adSetId- Only this synced ad set, with its ads.
campaignId- Only this synced campaign, with its ad sets and ads.
Response
jobId- The sync job.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404The ad account or object isn't synced.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/sync" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 8a27ad76-5ae4-41dc-9522-bc9eb346db7e" \
-H "Content-Type: application/json" \
-d '{
"adAccountId": "act_741877585619437",
"adId": "120288304425086360",
"adSetId": "120240541407845332",
"campaignId": "120227168091908311"
}'Change history
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
objectId | string | Optional | A campaign, ad set or ad by Meta ID, or the ad account (act_…). |
adId | string | Optional | A Pluto ad (its Meta ad). |
adSetId | string | Optional | A Pluto ad set (its Meta ad set). |
launchId | string | Optional | A launch: its campaign and everything in it. |
campaignId | string | Optional | A campaign by Meta ID, with its ad sets and ads. |
adAccountId | string | Optional | Everything in one ad account. |
who | string | Optional | Comma-separated: person, agent, loop, mcp, api_key, pluto, meta_user, meta_app, meta. |
source | string | Optional | Comma-separated: pluto, meta_ui, other_app, meta_system. |
field | string | Optional | Comma-separated: budget, status, bid, targeting, creative, ... |
since | string | Optional | From this time on (RFC 3339). |
until | string | Optional | Before this time (RFC 3339). |
fresh | string | Optional | true: read Meta's newest activity for the object or account first. |
after | string | Optional | Cursor: nextAfter from the previous page. |
limit | string | Optional | Page size (1-200, default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Changes, newest first.
items[].at- When it happened.
items[].currency- The amounts' currency.
items[].decision- What led to a Pluto change: the chat and model, or the loop's version, step and reason.
items[].description- Meta's words for it.
items[].eventType- Meta's event type, or what Pluto sent.
items[].field- 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[].from- The old value (money as a decimal string).
items[].fromMinor- The old amount in the currency's minor units (an integer).
items[].id- The change's ID.
items[].level- What it changed.One of
account,campaign,ad_set,ad items[].metrics- The object's metrics over the 7 days before a Pluto change.
items[].objectitems[].object.adAccountId- The ad account (
act_…). items[].object.adSetId- Its ad set's Meta ID.
items[].object.campaignId- Its campaign's Meta ID.
items[].object.entityId- Its ad or ad set in Pluto, if Pluto published it.
items[].object.id- The object's ID on its platform (platforms other than Meta).
items[].object.launchId- The launch that published it, if Pluto did.
items[].object.metaId- The Meta ID (Meta's history).
items[].object.name- Its name.
items[].perioddailyorlifetimefor budgets.items[].platform- The platform, on histories of platforms other than Meta.
items[].source- Where it came from (
platform: found on a platform other than Meta, in its own tool, another app or the platform itself).One ofpluto,meta_ui,other_app,meta_system,platform items[].to- The new value (money as a decimal string).
items[].toMinor- The new amount in the currency's minor units (an integer).
items[].valueKind- How to read
fromandto.creative: a live ad's creative content as JSON text (text,headline,description,cta,url,media, and for a carouselcards[{media,headline,description,url}] withbestCardsFirstandendCard, andurlTags);fromis null when the content before wasn't recorded.One ofmoney,status,text,json,creative,none items[].valuesRemoved- The platform's terms limit how long its values are kept:
from,toand the name were removed after that. items[].whoitems[].who.application- The app Meta says it came through.
items[].who.applicationId- That app's Meta ID.
items[].who.approvalId- The approval that let it run.
items[].who.id- A Pluto person, agent, key or loop ID, or Meta's user ID.
items[].who.kind- Who made it.One of
person,agent,loop,mcp,api_key,pluto,meta_user,meta_app,meta,platform items[].who.loopId- The loop.
items[].who.metaActorName- Who Meta says made it.
items[].who.name- Their name.
items[].who.onBehalfOf- The person a Pluto change was made for.
items[].who.origin- Where a Pluto change came from (app, api_key, mcp, agent_chat, loop).
items[].who.originId- The Agent chat or loop run.
items[].withheld- 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. nextAfter- Pass as
afterfor the next page; null on the last. readAt- When the ad account's activity log was last read in full (one account asked).
curl "$PLUTO_API/meta/changes" \
-H "Authorization: Bearer $PLUTO_KEY"