API reference

Meta

The Meta connection, ad accounts, Pages, imports and changes to what's live in Meta.

GET/integrations/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.

Permission: read

Parameters

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

Response200 OK

adAccountLimitobject or null
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 a 402 plan_limit with feature: ad_accounts: feature, reason plan_cap or trial, limit, used, plan, nextAction, upgradeTo, upgradeUrl) and heldBack [{id, name}]. Accounts already connected always stay. Null when none are waiting; on a plan that takes them, the next sync adds them.
adAccountsarray of objectsRequired
The ad accounts that are on: synced, counted against the plan's cap and offered everywhere in Pluto.
adAccounts[].accountStatusintegerRequired
Meta's account status.
adAccounts[].attentionobject or nullRequired
What Meta needs a person to do in Meta before this ad account takes more changes; null when nothing.
adAccounts[].attention.blockingbooleanRequired
Whether it stops changes (a review or an overdue payment doesn't yet).
adAccounts[].attention.checkablebooleanRequired
Whether POST /integrations/meta/attention/check can confirm it's done; a status Meta reports on the account clears with the next sync.
adAccounts[].attention.clearsAtPublishbooleanRequired
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/check can find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes.
adAccounts[].attention.detailstring or nullRequired
Meta's own words.
adAccounts[].attention.linestringRequired
One line under the title.
adAccounts[].attention.linkobject or nullRequired
The Meta page to do it in: label, labelCode (the label's stable code, such as meta_link_open_meta), url.
adAccounts[].attention.needstringRequired
What Meta needs, e.g. confirm_identity, audience_terms, policy_block, account_unpaid.
adAccounts[].attention.nextstringRequired
What to do, in one sentence.
adAccounts[].attention.profilestring or nullRequired
The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
adAccounts[].attention.profileActsbooleanRequired
Only that profile can do it (confirming it's them, a pending step, two-factor).
adAccounts[].attention.reasonstringRequired
One short sentence for a change that failed because of it.
adAccounts[].attention.sincestring (date-time) or nullRequired
When Meta said so; null for the account's status.
adAccounts[].attention.titlestringRequired
A short title: "Confirm the identity in Meta".
adAccounts[].attention.whostringRequired
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[].businessobject or nullRequired
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[].capacityobject or nullRequired
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) and readAt (when the ads were counted); null until a sync counted them. Information only: Pluto never holds an account back for it.
adAccounts[].countrystring or nullRequired
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[].currencystringRequired
ISO 4217; the account's amounts are in it.
adAccounts[].idstringRequired
act_…
adAccounts[].namestringRequired
Name.
adAccounts[].pageIdsarray of stringsRequired
Pages it may publish from.
adAccounts[].pixelsarray of objectsRequired
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[].idstringRequired
The pixel (dataset) ID, what a launch's pixel takes.
adAccounts[].pixels[].namestring or nullRequired
Its name in Meta; null when it has none.
adAccounts[].spendingLimitobject or nullRequired
Meta's account spending limit and what was spent toward it; null until Meta reported it.
adAccounts[].spendingLimit.amountstring or nullRequired
The limit in the ad account currency; null when the account has none.
adAccounts[].spendingLimit.readAtstring (date-time)Required
When Meta reported it.
adAccounts[].spendingLimit.spentstringRequired
Spent toward the limit (in total when there's none).
adAccounts[].timezonestringRequired
IANA time zone.
adAccountsOffarray of objectsRequired
The other ad accounts Meta shares, turned off: not synced, counted or offered until PUT /integrations/meta/ad-accounts/{id}/sync turns them on. A new ad account arrives here.
adAccountsOff[].accountStatusintegerRequired
Meta's account status.
adAccountsOff[].businessobject or nullRequired
The business (Business Manager) that owns the ad account: id, name; null when Meta reports none.
adAccountsOff[].countrystring or nullRequired
The country of the ad account's business address (ISO 3166); null when Meta reports none.
adAccountsOff[].currencystringRequired
ISO 4217.
adAccountsOff[].idstringRequired
act_…
adAccountsOff[].namestringRequired
Name.
adAccountsOff[].timezonestringRequired
IANA time zone.
connectedAtstring (date-time) or null
Connected.
lastSyncobject or null
The latest sync job: jobId, status, error, errorCode and errorParams (a registered error's stable code and the values it names, absent for an error without one), finishedAt; null before the first.
metaUserobject or null
The Meta user who connected: id, name.
missingPermissionstring or null
The permission Meta said is missing (e.g. ads_management), when it named one.
missingPermissionsarray of strings
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.
pagesarray of objectsRequired
The Pages that are on: offered wherever a Page is chosen.
pages[].idstringRequired
Page ID.
pages[].instagramobject or null
Linked Instagram account: id, username.
pages[].namestringRequired
Name.
pagesOffarray of objectsRequired
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[].idstringRequired
Page ID.
pagesOff[].instagramobject or null
Linked Instagram account: id, username.
pagesOff[].namestringRequired
Name.
reasonstring or null
Why it needs reconnecting: expired (the token is gone) or permission (Meta no longer grants one); null otherwise.One of expired, permission
scopesarray of stringsRequired
Permissions Meta granted.
statusstringRequired
Status.One of connected, reauthorize, disconnected
statusReasonstring or null
Why it needs attention.
syncedAtstring (date-time) or null
Last completed sync.
tokenExpiresAtstring (date-time) or null
When Meta's token expires (about 60 days after connecting; reconnecting renews it).
tokenExpirystring or null
Where the token is in its life: expiring within 7 days of tokenExpiresAt (admins get an Inbox notice and an email; reconnecting renews it), expired after it. Null without a connection or when Meta gave no expiry.One of valid, expiring, expired
versionintegerRequired
Version.

Errors

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

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe Meta ad account's ID.
subtypequerystringOptionalOnly this Meta subtype, e.g. CUSTOM or LOOKALIKE.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstringRequired
The ad account.
itemsarray of objectsRequired
Audiences.
items[].createdTimestring (date-time) or null
items[].deliveryStatusobject or null
Meta's status: code and description.
items[].deliveryStatus.codeinteger or null
items[].deliveryStatus.descriptionstring or null
items[].descriptionstring or null
Description.
items[].idstringRequired
Meta audience ID.
items[].kindstringRequired
What it is.One of custom, lookalike, other
items[].lookalikeobject or null
Lookalikes: what they're built from.
items[].lookalike.countrystring or null
items[].lookalike.originAudienceIdsarray of strings
items[].lookalike.rationumber or null
Share of the country, e.g. 0.01 for 1 %.
items[].namestringRequired
Name.
items[].operationStatusobject or null
Meta's status: code and description.
items[].operationStatus.codeinteger or null
items[].operationStatus.descriptionstring or null
items[].sizeobject or null
Meta's size estimate; null when Meta can't estimate it (never 0 for unknown).
items[].size.lowerinteger or null
items[].size.upperinteger or null
items[].specialAdCategoryAllowedbooleanRequired
Usable in housing, employment and financial ads (lookalikes aren't).
items[].subtypestring or null
Meta's subtype: CUSTOM, LOOKALIKE, WEBSITE, ENGAGEMENT, …
items[].updatedTimestring (date-time) or null

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-After seconds. 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/integrations/meta/ad-accounts/{id}/minimum-budget

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstringRequired
The ad account.
currencystringRequired
The ad account's currency (ISO 4217).
dailystring or nullRequired
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-After seconds. 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"
PUT/integrations/meta/ad-accounts/{id}/pages

Set an ad account's Pages

Pages an ad account may publish from.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

pageIdsarray of stringsRequired
At least one.

Response200 OK

adAccountIdstringRequired
Account.
pageIdsarray of stringsRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
    ]
  }'
PUT/integrations/meta/ad-accounts/{id}/spending-limit

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

amountstring or nullRequired
The spending limit in the ad account currency, e.g. 5000.00; null removes it.

Response202 Accepted

adAccountIdstringRequired
The ad account.
amountstring or nullRequired
The limit asked for; null when it's removed.
currencystringRequired
The ad account currency (ISO 4217).
currentobject or nullRequired
The limit as Meta last reported it, before this change; null when Meta hasn't reported it yet.
current.amountstring or nullRequired
The limit in the ad account currency; null when the account has none.
current.readAtstring (date-time)Required
When Meta reported it.
current.spentstringRequired
Spent toward the limit (in total when there's none).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
  }'
PUT/integrations/meta/ad-accounts/{id}/sync

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

enabledbooleanRequired
true turns it on, false off.

Response200 OK

adAccountIdstringRequired
Account.
enabledbooleanRequired
Whether it's on now.
jobIdstring (uuid) or nullRequired
The sync that brings it in, when this turned it on.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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
  }'
GET/integrations/meta/ad-accounts/{id}/targeting-search

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.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe Meta ad account's ID.
qquerystringOptionalWhat to look for (1-100 characters).
typequerystringOptionalOnly this kind.
specialAdCategoryquerystringOptionalOnly options Meta allows in this special ad category, e.g. HOUSING.
limitquerystringOptionalResults, 1-100 (default 25).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstringRequired
The ad account.
itemsarray of objectsRequired
Matches, as Meta ranks them (not exhaustive).
items[].categorystring or null
interest, behaviour or demographic.
items[].descriptionstring or null
Meta's description.
items[].idstringRequired
Meta's ID: use it with type in set_targeting's detailedTargeting.
items[].namestringRequired
Name.
items[].patharray of stringsRequired
Where it sits in Meta's taxonomy, broadest first.
items[].sizeobject or null
Meta's audience size estimate {lower, upper}; null when Meta gives none.
items[].targetablebooleanRequired
set_targeting takes it (in the special ad category searched for, if any).
items[].typestring or null
interests, behaviors, life_events, industries, income, family_statuses, work_positions, work_employers, education_schools or education_majors.
querystringRequired
What was searched for.
specialAdCategorystring or null
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-After seconds. 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"
GET/integrations/meta/ad-sets

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.

Permission: read

Parameters

NameTypeRequiredDescription
adAccountIdquerystringOptionalact_… (optional).
campaignIdquerystringOptionalOnly this campaign's ad sets.
searchquerystringOptionalPart of the name (case-insensitive) or the exact Meta ID.
statusquerystringOptionalOnly this effective status (effective_status, else status), e.g. ACTIVE; filtered before paging.
afterquerystringOptionalCursor.
limitquerystringOptionalPage size (1-500, default 200).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].adAccountIdstringRequired
act_…
items[].adAccountNamestring
The ad account's name.
items[].ageDaysinteger or null
Whole days since createdTime (0 on the first day).
items[].automaticPlacementsboolean or null
Whether Meta chooses the placements (Advantage+ placements).
items[].bidStrategystring or null
Bid strategy.
items[].campaignIdstringRequired
Meta campaign ID.
items[].campaignNamestring or null
The campaign's name, when synced.
items[].changesBlockedstring or null
Why Meta's API can't change it (a legacy Advantage+ shopping or app campaign, or something in one); null when it can.
items[].createdTimestring (date-time) or null
When it was created in Meta; null until the sync has read it.
items[].currencystringRequired
ISO 4217.
items[].dailyBudgetstring or null
In currency; null when Meta reported none, never zero.
items[].deliveryIssuesarray of objects or null
Issues Meta reports that keep it from delivering; [] when there are none, null until read.
items[].deliveryIssues[].errorCodeinteger or null
Meta's error code.
items[].deliveryIssues[].errorMessagestring or null
Meta's message.
items[].deliveryIssues[].errorSummarystring or null
Meta's short summary.
items[].deliveryIssues[].errorTypestring or null
HARD_ERROR (stops delivery) or SOFT_ERROR for ads; Meta doesn't publish the values for campaigns and ad sets.
items[].deliveryIssues[].levelstring or null
Where Meta places the issue (campaign, ad set or ad).
items[].effectiveStatusstring or null
Effective status.
items[].endTimestring (date-time) or null
Delivery end.
items[].hasDeliveryIssueboolean or null
Whether Meta reports a delivery issue.
items[].idstringRequired
Meta ad set ID.
items[].launchIdstring (uuid) or null
The Pluto launch that manages it, if any.
items[].learningobject or null
The learning stage: status, conversions (in the learning phase; 0 once out), lastSignificantEditAt (the edit that restarted learning), attributionWindows.
items[].learningStatusstring or null
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[].lifetimeBudgetstring or null
In currency; null when Meta reported none, never zero.
items[].namestringRequired
Name.
items[].placementsobject or null
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[].publisherPlatformsarray of strings or null
The platforms chosen; [] when Meta chooses (automaticPlacements).
items[].smartPromotionTypestring or null
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[].specialAdCategoriesarray of strings or null
The campaign's special ad categories; [] when it declares none.
items[].startTimestring (date-time) or null
Delivery start.
items[].statusstringRequired
Configured status.
items[].updatedTimestring (date-time)Required
When it last changed in Meta.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

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

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Only for a launch's ad set: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted in Meta.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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
  }'
PATCH/integrations/meta/ad-sets/{id}/bid

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

bidAmountstring
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).
bidStrategystring
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
roasGoalstring
Meta's ROAS goal, e.g. "2.5": at most four decimals, 0.01 to 1000 (with LOWEST_COST_WITH_MIN_ROAS).

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
  }'
PATCH/integrations/meta/ad-sets/{id}/budget

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

amountstringRequired
The new budget in the ad account currency; the budget keeps its period (daily, lifetime or total).

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
  }'
POST/integrations/meta/ad-sets/{id}/copies

Duplicate a Meta ad set

Copies the ad set (deepCopy: with its ads), into its campaign or intoCampaignId, paused unless statusOption says otherwise.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

deepCopyboolean
Ad sets and campaigns: copy what is inside too (default false).
endTimestring (date-time)
Ad sets and campaigns: when the copied ad sets end.
intoAdSetIdstring
Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignIdstring
Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsobject
renameOptions.prefixstring
Put before the name.
renameOptions.strategystring
Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of ONLY_TOP_LEVEL_RENAME, DEEP_RENAME, NO_RENAME
renameOptions.suffixstring
Put after the name (Meta's default is a localized " - Copy").
startTimestring (date-time)
Ad sets and campaigns: when the copied ad sets start.
statusOptionstring
How the copy starts (default PAUSED).One of PAUSED, ACTIVE, INHERITED_FROM_SOURCE

Response202 Accepted

jobIdstring (uuid)Required
The copy job; its items name each copy (output.copiedId).
levelstringRequired
What is copied.One of campaign, ad_set, ad
objectsintegerRequired
How many objects the job copies.
sourceIdstringRequired
The original's ID on its platform.
statusOptionstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
  }'
POST/integrations/meta/ad-sets/{id}/delete

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Only for a launch's ad set: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted in Meta.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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
  }'
PATCH/integrations/meta/ad-sets/{id}/schedule

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

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

endTimestring (date-time)
When it stops; in the future and after the start.
schedulearray of objects
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[].daysarray of integersRequired
0 is Sunday … 6 is Saturday.
schedule[].endMinuteintegerRequired
Minute of the day it ends, on the hour, at least an hour later (up to 1440).
schedule[].startMinuteintegerRequired
Minute of the day it starts, on the hour (0, 60, … 1380).
scheduleTimezonestring
Meta's ad scheduling: whose time zone the schedule follows (default viewer).One of viewer, account
startTimestring (date-time)
When the ad set starts delivering.

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
  }'
POST/integrations/meta/ad-sets/{id}/status

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

statusstringRequired
Delivery.One of ACTIVE, PAUSED

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
  }'
PATCH/integrations/meta/ad-sets/{id}/targeting

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

beneficiarystring
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.
customAudiencesarray of strings
Custom or lookalike audiences to reach; replaces the list ([] removes them).
detailedExclusionsarray of objects
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[].idstringRequired
Meta's ID (from search_targeting).
detailedExclusions[].namestring
Its name (optional, for people reading the change).
detailedExclusions[].typestringRequired
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
detailedTargetingarray of array of objects
Interests, behaviors and demographics (IDs and type from 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.
excludedAudiencesarray of strings
Audiences to exclude; replaces the list.
excludedLocationsobject
Where they don't run; replaces the excluded locations ({} removes them).
excludedLocations.citiesarray of objects
Cities, optionally with a radius.
excludedLocations.cities[].distanceUnitstring
Unit of radius.One of mile, kilometer
excludedLocations.cities[].keystringRequired
Meta's city key.
excludedLocations.cities[].radiusinteger
Around the city: 10-50 miles or 17-80 kilometers.
excludedLocations.countriesarray of strings
Countries, e.g. ["US", "DK"].
excludedLocations.regionsarray of objects
Regions (states, provinces), up to 200.
excludedLocations.regions[].keystringRequired
Meta's location key (from Meta's targeting search).
excludedLocations.zipsarray of objects
Postal codes (e.g. US:94304).
excludedLocations.zips[].keystringRequired
Meta's location key (from Meta's targeting search).
genderstring
Who by gender.One of All, Men, Women
locationsobject
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.citiesarray of objects
Cities, optionally with a radius.
locations.cities[].distanceUnitstring
Unit of radius.One of mile, kilometer
locations.cities[].keystringRequired
Meta's city key.
locations.cities[].radiusinteger
Around the city: 10-50 miles or 17-80 kilometers.
locations.countriesarray of strings
Countries, e.g. ["US", "DK"].
locations.regionsarray of objects
Regions (states, provinces), up to 200.
locations.regions[].keystringRequired
Meta's location key (from Meta's targeting search).
locations.zipsarray of objects
Postal codes (e.g. US:94304).
locations.zips[].keystringRequired
Meta's location key (from Meta's targeting search).
maxAgeinteger
13-65 (65 means 65+).
minAgeinteger
13-65.
payerstring
Who pays for the ads (with beneficiary), for ads that reach the EU.
placementsobject
placements.advantagebooleanRequired
Advantage+ placements: Meta chooses (leave platforms out).
placements.platformsarray of strings
Manual placements: the platforms.
placements.positionsarray of strings
Positions of the chosen platforms; left out means all of them.

Response202 Accepted

adSetIdstring (uuid) or null
The Pluto ad set, when a launch manages it.
appliedThroughstringRequired
draft: through the launch that manages the ad set; meta: on Meta's own targeting spec.One of draft, meta
availableAtstring (date-time)Required
When it runs.
fieldsarray of stringsRequired
The targeting fields the change names.
jobIdstring (uuid)Required
The job making the change in Meta; follow it with wait_for_job.
metaAdSetIdstringRequired
Meta's ad set ID.
specialAdCategoriesarray of stringsRequired
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, and fix: Meta Ads Manager on the ad set; send beneficiary and payer with 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 422 naming 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-After seconds. 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"
      ]
    }
  }'
GET/integrations/meta/ads

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

Permission: read

Parameters

NameTypeRequiredDescription
adAccountIdquerystringOptionalact_… (optional).
campaignIdquerystringOptionalOnly this campaign's ads.
adSetIdquerystringOptionalOnly this ad set's ads.
searchquerystringOptionalPart of the name (case-insensitive) or the exact Meta ID.
statusquerystringOptionalOnly this effective status (effective_status, else status), e.g. ACTIVE; filtered before paging.
afterquerystringOptionalCursor.
limitquerystringOptionalPage size (1-500, default 200).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].adAccountIdstringRequired
act_…
items[].adAccountNamestring
The ad account's name.
items[].adSetIdstringRequired
Meta ad set ID.
items[].ageDaysinteger or null
Whole days since createdTime (0 on the first day).
items[].automaticPlacementsboolean or null
Whether Meta chooses the placements (Advantage+ placements).
items[].campaignIdstringRequired
Meta campaign ID.
items[].changesBlockedstring or null
Why Meta's API can't change it (a legacy Advantage+ shopping or app campaign, or something in one); null when it can.
items[].createdTimestring (date-time) or null
When it was created in Meta; null until the sync has read it.
items[].creativeIdstring or null
Meta creative ID.
items[].creativeTypestring or null
The creative's type as Meta reports it (object_type).One of APPLICATION, DOMAIN, EVENT, INVALID, PAGE, PHOTO, POST_DELETED, PRIVACY_CHECK_FAIL, SHARE, STATUS, STORE_ITEM, VIDEO
items[].deliveryIssuesarray of objects or null
Issues Meta reports that keep it from delivering; [] when there are none, null until read.
items[].deliveryIssues[].errorCodeinteger or null
Meta's error code.
items[].deliveryIssues[].errorMessagestring or null
Meta's message.
items[].deliveryIssues[].errorSummarystring or null
Meta's short summary.
items[].deliveryIssues[].errorTypestring or null
HARD_ERROR (stops delivery) or SOFT_ERROR for ads; Meta doesn't publish the values for campaigns and ad sets.
items[].deliveryIssues[].levelstring or null
Where Meta places the issue (campaign, ad set or ad).
items[].effectiveStatusstring or null
Effective status.
items[].hasDeliveryIssueboolean or null
Whether Meta reports a delivery issue.
items[].idstringRequired
Meta ad ID.
items[].launchIdstring (uuid) or null
The Pluto launch that manages it, if any.
items[].learningobject or null
The learning stage: status, conversions (in the learning phase; 0 once out), lastSignificantEditAt (the edit that restarted learning), attributionWindows.
items[].learningStatusstring or null
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[].namestringRequired
Name.
items[].placementsobject or null
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[].publisherPlatformsarray of strings or null
The platforms chosen; [] when Meta chooses (automaticPlacements).
items[].smartPromotionTypestring or null
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[].specialAdCategoriesarray of strings or null
The campaign's special ad categories; [] when it declares none.
items[].statusstringRequired
Configured status.
items[].thumbnailUrlstring or null
Meta-hosted preview image link.
items[].updatedTimestring (date-time)Required
When it last changed in Meta.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

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

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Only for a launch's ad: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted in Meta.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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
  }'
POST/integrations/meta/ads/{id}/copies

Duplicate a Meta ad

Copies the ad into its ad set or intoAdSetId, paused unless statusOption says otherwise.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

deepCopyboolean
Ad sets and campaigns: copy what is inside too (default false).
endTimestring (date-time)
Ad sets and campaigns: when the copied ad sets end.
intoAdSetIdstring
Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignIdstring
Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsobject
renameOptions.prefixstring
Put before the name.
renameOptions.strategystring
Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of ONLY_TOP_LEVEL_RENAME, DEEP_RENAME, NO_RENAME
renameOptions.suffixstring
Put after the name (Meta's default is a localized " - Copy").
startTimestring (date-time)
Ad sets and campaigns: when the copied ad sets start.
statusOptionstring
How the copy starts (default PAUSED).One of PAUSED, ACTIVE, INHERITED_FROM_SOURCE

Response202 Accepted

jobIdstring (uuid)Required
The copy job; its items name each copy (output.copiedId).
levelstringRequired
What is copied.One of campaign, ad_set, ad
objectsintegerRequired
How many objects the job copies.
sourceIdstringRequired
The original's ID on its platform.
statusOptionstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
  }'
POST/integrations/meta/ads/{id}/delete

Delete a Meta ad

Irreversible: deletes the ad in Meta and reads it back; it then leaves the synced lists.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Only for a launch's ad: the draft version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted in Meta.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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
  }'
POST/integrations/meta/ads/{id}/status

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

statusstringRequired
Delivery.One of ACTIVE, PAUSED

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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/integrations/meta/ads/{id}/view

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstring or null
The ad account's ID on its platform (act_… on Meta).
adSetIdstring (uuid) or null
Ad set.
aspectRatiostring or null
As ad specs name it.
copyobject or nullRequired
The copy it runs with: primaryText, headline, description, callToAction, url; a launch ad adds its variations (primaryTexts, headlines, descriptions).
durationMsinteger or null
Videos: duration.
effectiveStatusstring or null
Delivery in Meta when it's live there.
expiresAtstring (date-time)Required
When the still URLs stop working.
formatstring or null
image, video or audio (an audio ad, where the platform has them).
hasAudioboolean or null
Videos: whether there is a sound track.
idstringRequired
The Pluto ad ID, or the Meta ad ID.
launchIdstring (uuid) or null
Launch.
mediaobject or null
A launch ad's creative.
media.archivedAtstring (date-time) or null
Archived; still counted toward media storage until deleted.
media.byteSizeinteger
Size in bytes.
media.contentTypestring
MIME type.
media.createdAtstring (date-time)
Added.
media.createdBystring (uuid)
Their ID.
media.createdByKindstring
Who added it.One of person, api_key, agent, system
media.deletedAtstring (date-time) or null
Deleted by a person: the files are gone and no longer counted.
media.durationMsinteger or null
Videos and audio files: duration.
media.errorstring or null
Why processing failed.
media.errorCodestring
A registered error's stable code (such as media_image_unreadable), for an app to say it in its language; absent for an error without one.
media.errorParamsobject
The values errorCode's sentence names, present exactly when it is.
media.folderIdstring (uuid) or null
Folder; null for the library root.
media.hasPreviewboolean
A preview image exists: an image's thumbnail or a video's poster frame.
media.heightinteger or null
Pixels, once processed.
media.idstring (uuid)Required
ID.
media.kindstring
Kind: a document is a PDF for document ads, in workspaces that run them; audio an MP3, OGG or WAV for audio ads, where a platform has them.One of image, video, document, audio
media.namestring
Name.
media.pageCountinteger or null
Documents: pages, once processed.
media.processedAtstring (date-time) or null
Processed.
media.sha256string or null
Hex SHA-256 of the content; null once an upload failed or was canceled.
media.sourcePlatformstring or null
The ad platform it came from: meta when Keep in sync or Import from Meta brought it; null for files people added.
media.sourceUrlstring or null
Where an import came from.
media.statusstring
Upload/processing status; only ready media publishes.One of uploading, processing, ready, failed
media.updatedAtstring (date-time)
Last change.
media.versioninteger
Increments on every change; send as expectedVersion.
media.warningsarray of objects
Provider-spec findings that don't block use.
media.warnings[].codestringRequired
resolution, aspect_ratio, format, duration, dimensions_unknown, duration_unknown; videos also placement_feed, placement_stories_reels, placement_in_stream, placement_reels, placement_instagram (a placement that crops or skips it) and poster_unavailable (Meta's own thumbnail is used).
media.warnings[].messagestringRequired
Finding.
media.warnings[].messageCodestring
A registered message's stable code (such as media_placement_feed), for an app to say it in its language.
media.warnings[].messageParamsobject
The values messageCode's sentence names, present exactly when it is.
media.widthinteger or null
Pixels, once processed.
metaAdIdstring or null
The ad in Meta, once published there.
namestringRequired
Name.
notestring or null
Why there's nothing (or less) to look at.
sourcestringRequired
launch: an ad of a Pluto launch (draft or published); meta: an ad that exists only in Meta.One of launch, meta
stillsarray of objectsRequired
In order: one for an image, up to 8 frames for a video.
stills[].atstring or null
Videos: the same as a timestamp, e.g. 0:04.
stills[].atMsinteger or null
Videos: where the frame is (ms).
stills[].heightintegerRequired
Pixels.
stills[].urlstringRequired
Short-lived URL of the JPEG.
stills[].widthintegerRequired
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-After seconds. 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"
GET/integrations/meta/attention

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.

Permission: read

Parameters

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

Response200 OK

dataarray of objectsRequired
Open needs.
data[].attentionobjectRequired
data[].attention.blockingbooleanRequired
Whether it stops changes (a review or an overdue payment doesn't yet).
data[].attention.checkablebooleanRequired
Whether POST /integrations/meta/attention/check can confirm it's done; a status Meta reports on the account clears with the next sync.
data[].attention.clearsAtPublishbooleanRequired
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/check can find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes.
data[].attention.detailstring or nullRequired
Meta's own words.
data[].attention.linestringRequired
One line under the title.
data[].attention.linkobject or nullRequired
The Meta page to do it in: label, labelCode (the label's stable code, such as meta_link_open_meta), url.
data[].attention.needstringRequired
What Meta needs, e.g. confirm_identity, audience_terms, policy_block, account_unpaid.
data[].attention.nextstringRequired
What to do, in one sentence.
data[].attention.profilestring or nullRequired
The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
data[].attention.profileActsbooleanRequired
Only that profile can do it (confirming it's them, a pending step, two-factor).
data[].attention.reasonstringRequired
One short sentence for a change that failed because of it.
data[].attention.sincestring (date-time) or nullRequired
When Meta said so; null for the account's status.
data[].attention.titlestringRequired
A short title: "Confirm the identity in Meta".
data[].attention.whostringRequired
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[].idstringRequired
The ad account (act_…) or Page ID.
data[].namestringRequired
Name.
data[].objectstringRequired
What needs it.One of ad_account, page

Errors

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

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

idstringRequired
The ad account (act_…) or Page ID.
objectstringRequired
What to check.One of ad_account, page

Response200 OK

atNextPublishbooleanRequired
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.
attentionobject or nullRequired
What is still needed; null when nothing.
attention.blockingbooleanRequired
Whether it stops changes (a review or an overdue payment doesn't yet).
attention.checkablebooleanRequired
Whether POST /integrations/meta/attention/check can confirm it's done; a status Meta reports on the account clears with the next sync.
attention.clearsAtPublishbooleanRequired
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/check can find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes.
attention.detailstring or nullRequired
Meta's own words.
attention.linestringRequired
One line under the title.
attention.linkobject or nullRequired
The Meta page to do it in: label, labelCode (the label's stable code, such as meta_link_open_meta), url.
attention.needstringRequired
What Meta needs, e.g. confirm_identity, audience_terms, policy_block, account_unpaid.
attention.nextstringRequired
What to do, in one sentence.
attention.profilestring or nullRequired
The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
attention.profileActsbooleanRequired
Only that profile can do it (confirming it's them, a pending step, two-factor).
attention.reasonstringRequired
One short sentence for a change that failed because of it.
attention.sincestring (date-time) or nullRequired
When Meta said so; null for the account's status.
attention.titlestringRequired
A short title: "Confirm the identity in Meta".
attention.whostringRequired
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.
clearedbooleanRequired
Meta takes changes again.
unknownstring or nullRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
  }'
GET/integrations/meta/campaigns

List synced campaigns

Synced campaigns of an ad account.

Permission: read

Parameters

NameTypeRequiredDescription
adAccountIdquerystringOptionalact_…
statusquerystringOptionalOnly this effective status (effective_status, else status), e.g. ACTIVE; filtered before paging.
searchquerystringOptionalPart of the name (case-insensitive) or the exact Meta ID.
afterquerystringOptionalCursor.
limitquerystringOptionalPage size (1-500, default 200).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].adAccountIdstring
act_…
items[].adAccountNamestring
The ad account's name.
items[].ageDaysinteger or null
Whole days since createdTime (0 on the first day).
items[].bidStrategystring or null
Bid strategy.
items[].budgetModestringRequired
Where the budget lives.One of campaign, ad_set
items[].changesBlockedstring or null
Why Meta's API can't change it (a legacy Advantage+ shopping or app campaign, or something in one); null when it can.
items[].createdTimestring (date-time) or null
When it was created in Meta; null until the sync has read it.
items[].currencystringRequired
ISO 4217.
items[].dailyBudgetstring or null
In currency; null when Meta reported none, never zero.
items[].deliveryIssuesarray of objects or null
Issues Meta reports that keep it from delivering; [] when there are none, null until read.
items[].deliveryIssues[].errorCodeinteger or null
Meta's error code.
items[].deliveryIssues[].errorMessagestring or null
Meta's message.
items[].deliveryIssues[].errorSummarystring or null
Meta's short summary.
items[].deliveryIssues[].errorTypestring or null
HARD_ERROR (stops delivery) or SOFT_ERROR for ads; Meta doesn't publish the values for campaigns and ad sets.
items[].deliveryIssues[].levelstring or null
Where Meta places the issue (campaign, ad set or ad).
items[].effectiveStatusstring or null
Effective status.
items[].hasDeliveryIssueboolean or null
Whether Meta reports a delivery issue.
items[].idstringRequired
Campaign ID.
items[].lifetimeBudgetstring or null
In currency; null when Meta reported none, never zero.
items[].namestringRequired
Name.
items[].objectivestringRequired
Objective.
items[].smartPromotionTypestring or null
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[].specialAdCategoriesarray of strings or null
The campaign's special ad categories; [] when it declares none.
items[].statusstringRequired
Configured status.
items[].updatedTimestring (date-time) or null
When it last changed in Meta (budget and spend cap edits don't move it).
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

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

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Only for a launch's campaign: the launch version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted in Meta.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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
  }'
PATCH/integrations/meta/campaigns/{id}/budget

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

amountstringRequired
The new budget in the ad account currency; the budget keeps its period (daily, lifetime or total).

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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"
  }'
POST/integrations/meta/campaigns/{id}/copies

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

deepCopyboolean
Ad sets and campaigns: copy what is inside too (default false).
endTimestring (date-time)
Ad sets and campaigns: when the copied ad sets end.
intoAdSetIdstring
Ads: the ad set (Meta ID, same ad account) to copy into.
intoCampaignIdstring
Ad sets: the campaign (Meta ID, same ad account) to copy into.
renameOptionsobject
renameOptions.prefixstring
Put before the name.
renameOptions.strategystring
Rename the copy only, everything copied, or nothing (default ONLY_TOP_LEVEL_RENAME).One of ONLY_TOP_LEVEL_RENAME, DEEP_RENAME, NO_RENAME
renameOptions.suffixstring
Put after the name (Meta's default is a localized " - Copy").
startTimestring (date-time)
Ad sets and campaigns: when the copied ad sets start.
statusOptionstring
How the copy starts (default PAUSED).One of PAUSED, ACTIVE, INHERITED_FROM_SOURCE

Response202 Accepted

jobIdstring (uuid)Required
The copy job; its items name each copy (output.copiedId).
levelstringRequired
What is copied.One of campaign, ad_set, ad
objectsintegerRequired
How many objects the job copies.
sourceIdstringRequired
The original's ID on its platform.
statusOptionstringRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
  }'
POST/integrations/meta/campaigns/{id}/delete

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Only for a launch's campaign: the launch version reviewed.

Response202 Accepted

deletesarray of objectsRequired
What is deleted in Meta.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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
  }'
POST/integrations/meta/campaigns/{id}/status

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.

Permission: publishCommand: send Idempotency-Key

Parameters

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

Request body

statusstringRequired
Delivery.One of ACTIVE, PAUSED

Response202 Accepted

availableAtstring (date-time)Required
When it runs: now, or when Meta's limit allows (4 budget changes per ad set per hour).
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
  }'
POST/integrations/meta/connect

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

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

Response201 Created

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

Disconnect Meta

Permission: adminCommand: send Idempotency-Key

Parameters

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

Response200 OK

adAccountLimitobject or null
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 a 402 plan_limit with feature: ad_accounts: feature, reason plan_cap or trial, limit, used, plan, nextAction, upgradeTo, upgradeUrl) and heldBack [{id, name}]. Accounts already connected always stay. Null when none are waiting; on a plan that takes them, the next sync adds them.
adAccountsarray of objectsRequired
The ad accounts that are on: synced, counted against the plan's cap and offered everywhere in Pluto.
adAccounts[].accountStatusintegerRequired
Meta's account status.
adAccounts[].attentionobject or nullRequired
What Meta needs a person to do in Meta before this ad account takes more changes; null when nothing.
adAccounts[].attention.blockingbooleanRequired
Whether it stops changes (a review or an overdue payment doesn't yet).
adAccounts[].attention.checkablebooleanRequired
Whether POST /integrations/meta/attention/check can confirm it's done; a status Meta reports on the account clears with the next sync.
adAccounts[].attention.clearsAtPublishbooleanRequired
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/check can find it still needed but doesn't clear it, and it clears at the next publish or ad change Meta takes.
adAccounts[].attention.detailstring or nullRequired
Meta's own words.
adAccounts[].attention.linestringRequired
One line under the title.
adAccounts[].attention.linkobject or nullRequired
The Meta page to do it in: label, labelCode (the label's stable code, such as meta_link_open_meta), url.
adAccounts[].attention.needstringRequired
What Meta needs, e.g. confirm_identity, audience_terms, policy_block, account_unpaid.
adAccounts[].attention.nextstringRequired
What to do, in one sentence.
adAccounts[].attention.profilestring or nullRequired
The Meta profile Pluto publishes with, by name; null when Meta didn't say it.
adAccounts[].attention.profileActsbooleanRequired
Only that profile can do it (confirming it's them, a pending step, two-factor).
adAccounts[].attention.reasonstringRequired
One short sentence for a change that failed because of it.
adAccounts[].attention.sincestring (date-time) or nullRequired
When Meta said so; null for the account's status.
adAccounts[].attention.titlestringRequired
A short title: "Confirm the identity in Meta".
adAccounts[].attention.whostringRequired
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[].businessobject or nullRequired
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[].capacityobject or nullRequired
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) and readAt (when the ads were counted); null until a sync counted them. Information only: Pluto never holds an account back for it.
adAccounts[].countrystring or nullRequired
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[].currencystringRequired
ISO 4217; the account's amounts are in it.
adAccounts[].idstringRequired
act_…
adAccounts[].namestringRequired
Name.
adAccounts[].pageIdsarray of stringsRequired
Pages it may publish from.
adAccounts[].pixelsarray of objectsRequired
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[].idstringRequired
The pixel (dataset) ID, what a launch's pixel takes.
adAccounts[].pixels[].namestring or nullRequired
Its name in Meta; null when it has none.
adAccounts[].spendingLimitobject or nullRequired
Meta's account spending limit and what was spent toward it; null until Meta reported it.
adAccounts[].spendingLimit.amountstring or nullRequired
The limit in the ad account currency; null when the account has none.
adAccounts[].spendingLimit.readAtstring (date-time)Required
When Meta reported it.
adAccounts[].spendingLimit.spentstringRequired
Spent toward the limit (in total when there's none).
adAccounts[].timezonestringRequired
IANA time zone.
adAccountsOffarray of objectsRequired
The other ad accounts Meta shares, turned off: not synced, counted or offered until PUT /integrations/meta/ad-accounts/{id}/sync turns them on. A new ad account arrives here.
adAccountsOff[].accountStatusintegerRequired
Meta's account status.
adAccountsOff[].businessobject or nullRequired
The business (Business Manager) that owns the ad account: id, name; null when Meta reports none.
adAccountsOff[].countrystring or nullRequired
The country of the ad account's business address (ISO 3166); null when Meta reports none.
adAccountsOff[].currencystringRequired
ISO 4217.
adAccountsOff[].idstringRequired
act_…
adAccountsOff[].namestringRequired
Name.
adAccountsOff[].timezonestringRequired
IANA time zone.
connectedAtstring (date-time) or null
Connected.
lastSyncobject or null
The latest sync job: jobId, status, error, errorCode and errorParams (a registered error's stable code and the values it names, absent for an error without one), finishedAt; null before the first.
metaUserobject or null
The Meta user who connected: id, name.
missingPermissionstring or null
The permission Meta said is missing (e.g. ads_management), when it named one.
missingPermissionsarray of strings
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.
pagesarray of objectsRequired
The Pages that are on: offered wherever a Page is chosen.
pages[].idstringRequired
Page ID.
pages[].instagramobject or null
Linked Instagram account: id, username.
pages[].namestringRequired
Name.
pagesOffarray of objectsRequired
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[].idstringRequired
Page ID.
pagesOff[].instagramobject or null
Linked Instagram account: id, username.
pagesOff[].namestringRequired
Name.
reasonstring or null
Why it needs reconnecting: expired (the token is gone) or permission (Meta no longer grants one); null otherwise.One of expired, permission
scopesarray of stringsRequired
Permissions Meta granted.
statusstringRequired
Status.One of connected, reauthorize, disconnected
statusReasonstring or null
Why it needs attention.
syncedAtstring (date-time) or null
Last completed sync.
tokenExpiresAtstring (date-time) or null
When Meta's token expires (about 60 days after connecting; reconnecting renews it).
tokenExpirystring or null
Where the token is in its life: expiring within 7 days of tokenExpiresAt (admins get an Inbox notice and an email; reconnecting renews it), expired after it. Null without a connection or when Meta gave no expiry.One of valid, expiring, expired
versionintegerRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/meta/disconnect" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 3f08512a-8b42-49c6-84f1-1a461646893c"
POST/integrations/meta/imports

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstringRequired
act_…
adSetIdsarray of strings
Ad sets: each becomes one launch into its existing campaign.
campaignIdsarray of strings
Campaigns: each becomes one launch with all its ad sets and ads.

Response202 Accepted

itemsarray of objectsRequired
One job item per pick.
items[].adSetsintegerRequired
Current ad sets it brings along, as last synced.
items[].adsintegerRequired
Current ads it brings along, as last synced.
items[].campaignIdstring or null
Ad sets: their campaign.
items[].effectiveStatusstring or null
Effective status.
items[].kindstringRequired
What was picked.One of campaign, adSet
items[].launchIdstring (uuid) or null
An earlier import's launch: importing again refreshes it.
items[].linkedLaunchIdstring (uuid) or null
Another launch already manages it; it can't be imported.
items[].metaIdstringRequired
Meta ID.
items[].namestringRequired
Name.
items[].statusstringRequired
Configured status.
jobIdstring (uuid)Required
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
    ]
  }'
POST/integrations/meta/imports/preview

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.

Permission: read

Parameters

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

Request body

adAccountIdstringRequired
act_…
adSetIdsarray of strings
Ad sets: each becomes one launch into its existing campaign.
campaignIdsarray of strings
Campaigns: each becomes one launch with all its ad sets and ads.

Response200 OK

adAccountIdstringRequired
act_…
currencystringRequired
ISO 4217.
itemsarray of objectsRequired
The picks.
items[].adSetsintegerRequired
Current ad sets it brings along, as last synced.
items[].adsintegerRequired
Current ads it brings along, as last synced.
items[].campaignIdstring or null
Ad sets: their campaign.
items[].effectiveStatusstring or null
Effective status.
items[].kindstringRequired
What was picked.One of campaign, adSet
items[].launchIdstring (uuid) or null
An earlier import's launch: importing again refreshes it.
items[].linkedLaunchIdstring (uuid) or null
Another launch already manages it; it can't be imported.
items[].metaIdstringRequired
Meta ID.
items[].namestringRequired
Name.
items[].statusstringRequired
Configured status.
notesarray of stringsRequired
What an import never does.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -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/integrations/meta/imports/{id}

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.

Permission: read

Parameters

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

Response200 OK

adAccountIdstring or null
act_…
createdAtstring (date-time)
Started.
failedintegerRequired
Failed.
finishedAtstring (date-time) or null
Finished.
itemsarray of objectsRequired
Picks.
jobIdstring (uuid)Required
The import job.
statusstringRequired
Job status.
succeededintegerRequired
Imported.
totalintegerRequired
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-After seconds. 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"
PUT/integrations/meta/pages/{id}/enabled

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.

Permission: adminCommand: send Idempotency-Key

Parameters

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

Request body

enabledbooleanRequired
true turns it on, false off.

Response200 OK

enabledbooleanRequired
Whether it's on now.
pageIdstringRequired
Page.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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
  }'
POST/integrations/meta/sync

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdstring
Only this ad account (act_…).
adIdstring
Only this synced ad.
adSetIdstring
Only this synced ad set, with its ads.
campaignIdstring
Only this synced campaign, with its ad sets and ads.

Response200 OK

jobIdstring (uuid)Required
The sync job.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404The ad account or object isn't synced.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/integrations/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"
  }'
GET/meta/changes

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.

Permission: read

Parameters

NameTypeRequiredDescription
objectIdquerystringOptionalA campaign, ad set or ad by Meta ID, or the ad account (act_…).
adIdquerystringOptionalA Pluto ad (its Meta ad).
adSetIdquerystringOptionalA Pluto ad set (its Meta ad set).
launchIdquerystringOptionalA launch: its campaign and everything in it.
campaignIdquerystringOptionalA campaign by Meta ID, with its ad sets and ads.
adAccountIdquerystringOptionalEverything in one ad account.
whoquerystringOptionalComma-separated: person, agent, loop, mcp, api_key, pluto, meta_user, meta_app, meta.
sourcequerystringOptionalComma-separated: pluto, meta_ui, other_app, meta_system.
fieldquerystringOptionalComma-separated: budget, status, bid, targeting, creative, ...
sincequerystringOptionalFrom this time on (RFC 3339).
untilquerystringOptionalBefore this time (RFC 3339).
freshquerystringOptionaltrue: read Meta's newest activity for the object or account first.
afterquerystringOptionalCursor: nextAfter from the previous page.
limitquerystringOptionalPage size (1-200, default 50).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

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

Errors

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