Public API

The Pluto Ads REST API: the same API the app uses, for your scripts, servers and integrations.

Everything a person does in the app, your code can do with its own credential, through the same actions, permissions and audit log. This page covers what every request shares. Each endpoint, with its fields and examples, is in the API reference.

Quickstart

Create a key in SettingsAPI (Settings, then API) with New API key, and choose Edit access. See Create an API key. Then set two variables:

Shell
export PLUTO_API=https://api.plutoads.ai/api/v1
export PLUTO_KEY=sk_live_...

List the workspace's launches:

curl -s "$PLUTO_API/launches?limit=2" \
  -H "Authorization: Bearer $PLUTO_KEY"

Create a launch. The Idempotency-Key makes a retry safe:

curl -s "$PLUTO_API/launches" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: holiday-gift-sets-2026" \
  -d '{"name": "Holiday gift sets, US"}'

The answer is 201 with the new launch and its version. Next, add ad sets and ads, then publish: see the Launches reference.

Authentication

Send a credential on every request as Authorization: Bearer <credential>.

CredentialStarts withFor
Secret API keysk_live_Scripts and servers. Has the scopes chosen when it was created.
Publishable API keypk_live_Read-only integrations. Has read only.
Access tokenAgents people connect from Claude, ChatGPT or Cursor, and agent credentials.

A key belongs to one workspace and needs no workspace header. A token that reaches several workspaces chooses one with Pluto-Workspace: <workspace ID>. A credential sent to a workspace it doesn't belong to gets 403.

Every credential acts for a person, and never does more than that person can do right now. If their role changes, the credential follows on its next request. If they leave, it stops.

Scopes

ScopeAllows
readReading launches, ads, media, results and settings
reviewCommenting, and approving or requesting changes on ads. Mentioning a guest on a launch that isn't shared with guests shares it, which also needs write.
writeDrafts, edits, media, workflow and settings
publishPublishing launches and every change to what runs on the ad platforms: delivery, budgets, bids, schedules, targeting, copies and deletes, and replies to comments on ads
adminThis workspace's members and guests, API keys, webhooks, the ad platform connections and settings
organizationThe organization's people, workspaces, plan, billing and usage limits. Comes with admin.

Publishing spends money, so it's its own scope: a key with write never changes a live ad. A secret key created through the API gets read, review, write and publish unless you name its scopes. Each endpoint's reference names the scope it needs. A credential can also hold single capabilities by ID, like ads:publish, beside or instead of these: the app's Access picks them. See Access.

Each scope holds a set of capabilities, one for each kind of thing you may do. For example, publish holds ads:publish (publishing and pushing edits), budgets:write (live budgets, bids and schedules), delivery:write (pausing and resuming), ads:delete (deleting in the ad platform) and social:write (comments on live ads). A refused request names the capability it needed in missingCapability (see forbidden). GET /me lists a person's capabilities in each workspace and what their organization role allows in each organization they belong to (organizations), and MCP's get_context lists a credential's own.

A credential's scopes can also name single workspace capabilities, for exactly what it needs: a key with ["ads:read", "delivery:write"] reads and pauses or resumes ads, and nothing else. Ask for what each capability requires beside it: delivery:write needs ads:read (or the read scope), and a request without it is 422, naming it. Organization access stays the organization scope, with admin. A scope you don't hold yourself is refused with 422 capability_not_grantable, naming the capability in missingCapability.

An API key's or agent credential's view (GET /api-keys, GET /agent-clients and what creating one answers) lists effectiveCapabilities: what it can do now, its scopes within its person's current role and what your organization lets members' API keys or agents hold. narrowedBy says why that's less than its scopes: role, policy or expired, and is empty when it can use every scope.

API access is included on every plan, the free trial too. An organization without a plan is read-only: reads work, and changes answer 402 payment_required.

Expiry and allowed addresses

API keys and agent credentials take two more limits when you create them:

  • expiresAt (RFC 3339): when the credential stops working by itself, within two years. Without it, it lasts 90 days, or your organization's limit when that's shorter. Send null for a credential that never expires, which an organization's limit doesn't allow (422).
  • allowedIps: up to 20 addresses (203.0.113.7) or CIDR ranges (198.51.100.0/24, 2001:db8::/32) it works from. A request from anywhere else gets 403, the credential's last use stays as it was, and the audit log records the refused address (once a minute per credential and address).
A key for one server, for 90 days
curl -s "$PLUTO_API/api-keys" \
  -H "Authorization: Bearer $PLUTO_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Reporting server", "kind": "secret", "scopes": ["read"],
        "expiresAt": "2027-02-02T00:00:00Z", "allowedIps": ["203.0.113.7"] }'

Rotating a key keeps its expiry and addresses. Revoking a credential also revokes the keys and agent credentials it created, and turns off the webhooks it created, so a leaked key takes everything it made down with it.

To give a credential less access without replacing it, narrow it: PATCH /api-keys/{id}, /agent-clients/{id} or /agent-connections/{id} with scopes, what it keeps. It keeps its secret, client and tokens, and from its next request does only that. A scope it doesn't hold now is 422: narrowing never adds access. What it made keeps its own access. Organization owners and admins narrow any credential in the organization with PATCH /organizations/{id}/credentials/{credentialId}.

Ad accounts

API keys, agent credentials and connected agents work in every ad account of their workspace, or in chosen ones: resources: { "adAccounts": ["act_123", "508123"] } when you create one (POST /api-keys, /agent-clients), when a person consents to an agent, and when you narrow one (PATCH, beside scopes). The IDs are the workspace's ad accounts on any platform, as list_platforms names them (Meta's act_..., X's ad account ID). Without resources a credential gets what its maker reaches (a person every ad account); "all" says so explicitly. An ID that isn't one of the workspace's ad accounts, or one the caller doesn't reach, is 422 on resources.adAccounts, and narrowing keeps only fewer, never more.

A key for one ad account
curl -s "$PLUTO_API/api-keys" \
  -H "Authorization: Bearer $PLUTO_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "US agency", "kind": "secret", "scopes": ["read", "write", "publish"],
        "resources": { "adAccounts": ["act_123"] } }'

A credential with chosen ad accounts:

  • Reads only what's in them. Anything in another ad account answers 404, as if it didn't exist, and lists leave it out: launches, ads and ad sets, the platforms' campaigns, ad sets and ads (name one of its ad accounts in adAccountId to list them), insights, leads from their ads, and the jobs it started itself.
  • Is refused acting on anything in another ad account, or naming one for something new (a launch, an import, a refresh): 403 with titleCode forbidden_outside_ad_accounts, recorded in the audit log. Queued work it started checks again when it runs.
  • Sees what has no ad account of its own only when everything it's about is in them: inbox items, Agent chats, loops and their runs, plans (change sets) and bulk edits, Creative Memory's experiments and monitors. One about nothing in an ad account (a notice, a loop set to every ad account) stays hidden from it.
  • Sees people's data by where it came from: leads and comments on ads' posts by their ad; organic leads, lead forms and comments on a Page's other posts only when every ad account that publishes from that Page is one of its own.
  • Reads or syncs what spans every ad account at once (Pluto Profit's store summary and product profitability, reading every Page's leads or comments now, a sync without adAccountId, an insights import without adAccountIds, and a platform's sync that always covers every ad account) only when it reaches every one of them; otherwise 403 with forbidden_outside_ad_accounts.
  • Works with what's in no ad account as before: the media library, drafts without an ad account, the workflow.
  • Holds nothing that spans every ad account, whatever its scopes say: the Agent, loops, members, integrations, everyone's credentials, the audit log and the organization. Its narrowedBy says resources.
  • Creates webhooks that deliver only its ad accounts' events (adAccountIds on the webhook), and credentials that reach no more ad accounts than it does. It manages only webhooks within its ad accounts.

Every credential's view says what it reaches: resources: { "adAccounts": "all" }, or each ad account with its id, name and platform. An agent reads its own in get_context (credential.resources).

An organization can limit what its members do with credentials (credentialPolicy on PATCH /organizations/{id}, for its owners and admins, who it doesn't bind). Each setting you leave out keeps its value:

  • membersMayCreateApiKeys, membersMayCreateAgentClients and membersMayCreateWebhooks: false lets only the organization's owners and admins create that kind. A member who tries gets 403, saying so in one sentence. What members made before keeps working.
  • membersAgentAccess: full (up to their role), build (what the app's Build and publish gives: viewing, launches and drafts, media, reviews, publishing, live budgets, pausing and resuming) or view (only viewing), for members' own agents. It applies on their agents' next request.
  • membersAgentClientAccess and membersApiKeyAccess: the same for the agent credentials and API keys members are accountable for. A new one beyond it is refused with 422 invalid, the problem under scopes saying what the organization allows, and no missingCapability: the role allows it, the organization doesn't. One made before is narrowed on its next request, its narrowedBy saying policy; its scopes stay as they are, so choosing full again gives back what it had. Until membersAgentClientAccess is set, agent credentials follow membersAgentAccess.
  • maxLifetimeDays: new credentials members make end within that many days. Without expiresAt they end at the limit when it's shorter than 90 days, and asking for more, or for null, is refused.

Agent credentials

Agent credentials are a client ID and secret for your own agent or service, created in SettingsAPI (Settings, then API). Your service trades them for a short-lived access token (OAuth client credentials) and asks for a new one when expires_in runs out. The token endpoint is found from the API's metadata, so nothing is hard-coded:

Get a token
AUTH_SERVER=$(curl -s "$PLUTO_API/.well-known/oauth-protected-resource" | jq -r '.authorization_servers[0]')
TOKEN_URL=$(curl -s "$AUTH_SERVER/.well-known/oauth-authorization-server" | jq -r '.token_endpoint')

curl -s "$TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d resource="$PLUTO_API/mcp"

The token works for this API and the MCP server. Keep resource: a token asked for without it, or for another resource, answers 401 unauthenticated.

To change the secret, POST /agent-clients/{id}/rotate: the answer holds the new clientSecret, once, and the clientId stays. The old secret gets no more tokens, and tokens it got answer 401 from their next request, so your service asks for a new one with the new secret. The credentials aren't revoked, so what they made keeps working; to end that too, revoke them instead.

Base URL and versions

Every endpoint is under https://api.plutoads.ai/api/v1. The API version is part of the path. The OpenAPI 3.1 document at $PLUTO_API/openapi.json describes every endpoint.

  • Requests and responses are JSON, with camelCase fields.
  • IDs are UUIDs, except the ad platforms' own IDs, written as each platform writes them: on Meta, act_ and digits for ad accounts and digits for campaigns, ad sets and ads.
  • Times are RFC 3339 in UTC.
  • Amounts are decimal strings in the ad account's currency, like "49.99". A JSON number where an amount belongs is a 400. null means unknown, never zero.

Idempotency

Every change is a command. Send an Idempotency-Key of 1 to 200 characters, and reuse it when you retry the same request. A retry after a timeout returns the stored result and changes nothing.

  • Derive keys from your own records (holiday-gift-sets-2026), not a random value per attempt.
  • Keys are remembered for 30 days, per credential.
  • The same key with a different body is a 409 with reason: command_id_reused.
  • Batch endpoints take items[], each with its own commandId that works the same way, and return an outcome per item: accepted, rejected with its errors, or conflict. Resend only what failed.

Without the header a request still runs once, but a retry can't be recognized and may act twice.

Versions and conflicts

What you can edit, like launches, ad sets, ads and media, has a version. Send the version you last read as expectedVersion when you update it.

Launches, ad sets and ads track versions per field: an update from an older version still applies when nobody changed the fields it touches. When someone did, the answer is 409 with the current state in current. Merge, then retry with expectedVersion set to current.version.

Pagination

Lists take limit and after, and answer with items and nextAfter. Pass nextAfter as after for the next page. It's null on the last page.

Next page
curl -s "$PLUTO_API/launches?limit=50&after=$NEXT_AFTER" -H "Authorization: Bearer $PLUTO_KEY"

Each endpoint's reference gives its default and largest limit, and the few lists shaped differently.

Rate limits

Limits count requests in 10-second windows.

WhoRequests per 10 seconds
Each API key or agent1,000
All API keys and agents of one workspace together3,000
Each person in the app300

People in the app don't count toward the workspace's total, so busy agents never slow them down. Over a limit, the answer is 429 with a Retry-After header in seconds. Wait that long, then retry with the same idempotency key.

A few endpoints have their own limits: Creative Memory search runs 4 searches at once per workspace, and refreshing analytics starts at most 2 imports per workspace every 15 minutes. Name the ad accounts you need with adAccountIds and the import reads only those, so it finishes sooner. Publishing jobs pace themselves to each ad platform's limits.

Errors

Errors are application/problem+json with a stable code. type links to the code's section in API errors.

422 invalid
{
  "type": "https://docs.plutoads.ai/api/errors#invalid",
  "title": "The request has 1 problem.",
  "status": 422,
  "code": "invalid",
  "errors": [{ "field": "name", "message": "Use a name of 1 to 120 characters." }]
}

Every response has x-request-id and x-trace-id headers, and every error repeats them as requestId and traceId. Include them when you report a problem.

Insights

GET /analytics/insights answers with the numbers the Analytics dashboard shows, for since and until (days in each ad account's time zone), optionally compared with compare_since and compare_until.

  • attribution: 7d_click_1d_view (Meta's default: each ad set's own attribution setting, as in Ads Manager), 7d_click, 1d_click, 28d_click or 1d_view.
  • Object filters: adAccountId, campaignId, adSetId, adId, launchId (and their names: account, campaign, adSet, launch). Repeat a parameter for alternatives; different parameters combine.
  • Segment filters: age (25-34), gender (female), country (US), region, placement (instagram|story), publisherPlatform (instagram), impressionDevice, devicePlatform, hour (00 to 23) and format (the ad format of a flexible or dynamic creative ad). Filter by one breakdown at a time: age and gender together, or one of the others. Segment filters use Meta's default attribution setting, and a comparison is made only when the segment rows cover the comparison period too (comparisonIncomplete otherwise).
  • breakdown: rows per launch, campaign, adSet or ad, or per segment: age, gender, ageGender, country, region, placement, publisherPlatform, impressionDevice, devicePlatform, hour, actionDevice, actionDestination, actionType, bodyAsset, titleAsset, imageAsset, videoAsset, callToActionAsset, linkUrlAsset, adFormatAsset or product; and Meta's dma, platformDevice (instagram|iphone), viewerHour (the hour in the viewer's time zone), actionReaction, actionVideoSound, actionVideoType and actionCarouselCard (a card by its name).
  • Metrics include every action Meta counts: action:<type> (a count), action_value:<type> (its value) and cost_per_action:<type>, for example action:offsite_conversion.custom.1234567890. Ad rows carry Meta's rankings (quality, engagementRate, conversionRate, with asOf).

Meta keeps numbers per segment for 13 months; coverage.breakdowns says, per breakdown, which days are in (from, through: the last day read to its end, and readAt), which rows answered (level: account for whole ad accounts, back 13 months; ad for a read narrowed to a campaign, ad set, ad or launch, whose segment rows cover the last two weeks), the days Meta couldn't produce (unreadDays, which keep the numbers they had) and which ad accounts haven't turned a breakdown on in Ads Manager. A measure Meta doesn't split by a breakdown is absent from its rows, never filled in from the totals, and reach, frequency and unique clicks are absent per segment. Meta splits no website or app conversion (purchases, their value, carts, checkouts, landing page views) by region, dma, viewerHour, product or an action breakdown: those answers carry a note saying so (segmentsNote for such a filter), and the conversions are absent, never 0.

While Pluto reads an ad account's older days again with newer fields (action types, video plays, watch time, rankings), coverage.history.fieldsCompleteFrom (and each account's history.fieldsCompleteFrom) is the first day every field is in. A metric read from those fields over a period starting earlier has incomplete: true, every entry of actionMetrics too, breakdown.incomplete for breakdown=actionType and breakdown.rankingsIncomplete for breakdown=ad.

With platform=linkedin, the segments are LinkedIn's: jobTitle, jobFunction, seniority, industry, companySize, company, country, region and county (its member demographics, values as LinkedIn's IDs) and conversionAction (a conversion rule's ID), placement, device, servingLocation (ON_SITE, OFF_SITE, UNKNOWN) and carouselCard (the card's index from 0), each read on its own; breakdown takes any of them and each row's name is LinkedIn's name for the value (English, empty when LinkedIn hasn't given one). Rows carry the shared metrics and LinkedIn's own (engagements, qualified_leads, open_rate and the rest). Demographics are approximate (none under 3 events), 24 to 48 hours late and reported for ad sets and up: with an adId or launchId filter they answer 422, and they have no conversion_value or roas. Their figures are LinkedIn's for exactly the period at the level filtered (ad account, campaignId or adSetId), read from LinkedIn the first time a period is asked: breakdown.basis is period, or days when LinkedIn didn't answer in time and the daily rows were added up. With a demographic filter, demographics.totals says the same of the totals, and the series are the daily rows. Their spend isn't adjusted for over delivery (spendAdjustedForOverDelivery: false), so it can add up to more than was billed. A demographic period starting more than 6 months ago must be whole months (422 otherwise), as LinkedIn keeps daily demographics 6 months. A conversion action splits only the conversions, a device has no conversions, and reach and frequency are absent per segment. LinkedIn's segments reach back 365 days.

Cost per purchase by placement, last 30 days
curl -s "$PLUTO_API/analytics/insights?since=2026-10-13&until=2026-11-11&breakdown=placement" \
  -H "Authorization: Bearer $PLUTO_KEY"

Asking for exactly what you need

  • metric: only these metrics, everywhere the answer has metrics (repeat it: metric=spend&metric=roas). Any ID of the platform's catalogue works, and action:<type> on Meta. An ID the platform doesn't report answers 422 with the closest IDs it does have.
  • definitions=true (implied by metric): each metric's definition in definitions: its name on the platform, unit (money, count, fraction, multiple, seconds), how it adds up (aggregation) and whether it's summable. sum metrics add up across days, rows and accounts. ratio metrics are recomputed from the sums, never averaged. window metrics (reach, frequency, unique clicks) are the platform's own figure for exactly the period and object: they never add up, so breakdown rows don't sum to the total.
  • With a breakdown: sort orders the rows by a metric (descending; -spend too, order=asc for ascending; rows without a value come last), limit (1 to 1000) pages them, and cursor takes the previous answer's breakdown.nextCursor (null on the last page). breakdown.rowsTotal counts every row in scope.
  • status (repeatable) keeps only ads with that status in the platform's words (ACTIVE is delivering now, PAUSED), and labelId or label only the ads Pluto labelled so: every figure, totals included, then covers just those ads.
  • thenBy splits every breakdown row again: by day, week or month (ad by day, country by week), or, with a breakdown by launch, campaign, ad set or ad, by a segment the platform reports (campaign by country). Each row gets by.rows, each { key, metrics } from its own sums: summed metrics add up to the row, ratios are recomputed, and reach, frequency and unique counts are never in a sub-row, since they don't add up.
  • platforms (names comma-separated, or all for every connected platform) answers several platforms at once: each platform's own answer under byPlatform, never added together, since each reports its own currencies, days and attribution. withheldPlatforms and refused name any platform that can't give numbers here, and why.
The 20 campaigns with the most spend, with ROAS
curl -s "$PLUTO_API/analytics/insights?since=2026-10-13&until=2026-11-11&breakdown=campaign&metric=spend&metric=roas&sort=spend&limit=20" \
  -H "Authorization: Bearer $PLUTO_KEY"

Ranking ads

GET /analytics/rankings ranks one platform's ads by a metric on the server, over every ad in scope, and answers the same as the MCP tool rank_ads for the same arguments. Use it for the top or bottom ads instead of reading a whole ad breakdown.

  • period names the days (last_30_days by default, last_7_days, this_month, all_time and others), or give since and until.
  • metric is what to rank by (spend by default): any per-ad metric the platform reports, and action:<type> or cost_per_action:<type> on Meta. order is desc or asc; by default the best come first, so costs rank lowest first.
  • limit (1 to 50, default 10) and offset page each ranking; nextOffset is the next page's offset.
  • Filters: adAccountId, campaignId, adSetId, adId and launchId (repeat them for several), the segment filters above by name, status (ACTIVE: running now), minSpend, minPurchases and currency. Set minSpend for ROAS or cost rankings, so ads with a single result don't lead.
  • metrics (repeat it, or all) picks the metrics each ad carries; creative=false leaves out what Creative Memory found in its files, and posts=true adds a Meta ad's Facebook and Instagram post links.

Every other parameter comes once, and an unknown one answers 422. Money is ranked within one currency: rankings has one entry per currency, each with adsInScope, totals and its ads in items, every ad with its name, campaign, ad set, links and metrics.

The 10 ads with the best ROAS last month, at least 500 spent
curl -s "$PLUTO_API/analytics/rankings?period=last_month&metric=roas&minSpend=500" \
  -H "Authorization: Bearer $PLUTO_KEY"

Results kept in Pluto

Some platforms' terms let their results show only inside Pluto's own app: on X, its numbers, names and statuses. An answer outside the app (the API, MCP, AI agents, exports) has those values as null and says why in withheldData, one entry per platform, with the platforms in the Pluto-Withheld header too:

JSON
{
  "withheld": true,
  "withheldData": [{
    "reason": "platform_terms",
    "platform": "x",
    "platformName": "X",
    "message": "The X terms don't let Pluto share X results outside Pluto's own app: not through the API, MCP, AI agents or exports. The results exist and are complete in Pluto; a null here is not missing data and not zero. The person sees them in Pluto: https://app.plutoads.ai/<workspace>/analytics?platform=x. Retrying, or asking another tool or endpoint, gives the same answer. Still usable here: the IDs of the X objects, the names, labels and launches Pluto owns, the statuses Pluto set, and every other platform's data.",
    "appUrl": "https://app.plutoads.ai/<workspace>/analytics?platform=x",
    "dataExists": true,
    "retryable": false,
    "stillAvailable": ["The IDs of the X ad accounts, campaigns, ad groups and ads", "Names, labels and launches Pluto owns", "Statuses Pluto set", "Every other platform's data"]
  }]
}

The results exist and are complete in Pluto: the nulls are not missing data or zero. Asking again, here or through another endpoint or tool, gives the same answer. Send the person to appUrl, and keep working with the IDs, Pluto's own records and every other platform's data.

Ad platforms

A launch publishes to Meta or LinkedIn or X. GET /platforms lists the platforms the workspace can use, each with its own words, what Pluto Ads can do there (capabilities) and what its terms allow (policy). Pass a platform's platform value wherever a route takes platform. Without it, a route means Meta.

  • A LinkedIn launch sets "platform": "linkedin" and a LinkedIn ad account when it's created. Its campaign and ad set settings go in platformSettings, with the fields, options and rules of GET /platforms/linkedin/spec. GET /platforms/linkedin/targeting searches LinkedIn's audience values.
  • Reads take platform: GET /analytics/insights, GET /changes, GET /leads, and the synced campaigns, ad sets and ads at GET /platforms/linkedin/campaigns, /ad-sets and /ads.
  • The connection is GET /integrations/linkedin, with POST /integrations/linkedin/sync and POST /integrations/linkedin/disconnect. POST /integrations/linkedin/connect returns a consent URL for a person to open in their browser. An API key can't connect.
  • LinkedIn's numbers use UTC days (dayBasis is utc) and count each conversion in its conversion rule's windows, so attribution is null. From settlingFrom on, LinkedIn may still change the numbers.
  • GET /analytics/insights with platform=linkedin carries every metric LinkedIn reports beside the shared ones, in the totals and every breakdown row: engagements, reactions, likes, comments, shares, follows, lead form opens, qualified leads, sends, opens, registrations, job applications, video starts and watch time (seconds), document and carousel card views, the viral (earned) figures, the rates and costs over them (such as open_rate and cost_per_qualified_lead), and average_dwell_time and audience_penetration as LinkedIn's figures for exactly the period (the windows reach is read for) when the scope is one ad account, campaign or ad set. Segments: see Insights.
Create a LinkedIn launch
curl -s "$PLUTO_API/launches" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wholesale-partners-fall-2026" \
  -d '{
    "name": "Wholesale partners, fall",
    "platform": "linkedin",
    "adAccountId": "512345678",
    "platformSettings": {
      "campaign": { "objective": "WEBSITE_VISIT" },
      "adSet": { "page": "80412345", "dailyBudget": "50.00" }
    }
  }'
  • The X connection is GET /integrations/x, with POST /integrations/x/sync and POST /integrations/x/disconnect. POST /integrations/x/connect returns a consent URL for a person to open in their browser. An API key can't connect. PUT /integrations/x/ad-accounts/{id}/sync turns an ad account on or off, and PUT /integrations/x/pages/{id}/enabled an X account ads run as (identities and identitiesOff in the connection).

  • X's terms keep what Pluto Ads reads from X inside Pluto Ads (policy.dataLeavesUi is false in GET /platforms). In the connection, an ad account's name, currency, timeZone, approvalStatus and role, an X account's username and name, the payment methods' values (fundingSources) and notices are null, and the object says so with withheld: true. IDs, status, scopes, lastSync and credits (what the workspace's X API calls cost this month against its allowance) are there as on any platform.

  • One X account connects to one organization: a consent for an X account that another organization has connected returns to the app with x=error&reason=other_organization, and nothing changes for either.

  • An X launch sets "platform": "x" and an X ad account when it's created. Its settings go in platformSettings: campaign holds the campaign's, adSet what every ad group starts with, and an ad group's own platformSettings only the keys it changes. GET /platforms/x/spec has the fields, options, limits and rules.

LevelKeys
campaignobjective, fundingSource, dailyBudget, totalBudget, purchaseOrderNumber
adSetidentity (the X account's user ID), promotedOnly, whoCanReply, start, end, dailyBudget, totalBudget, acceleratedDelivery, goal, bidStrategy, bidAmount, payBy, frequencyCap, frequencyDays, conversionEvent, iosAppId, androidAppId, placements, advertiserDomain, categories, audienceExpansion, audience, trackingTags, leadForm
  • Amounts are decimal strings in the ad account's currency. The campaign's budgets cap what its ad groups spend together. null empties a key, and on an ad group it goes back to the launch's value.
  • A write refuses what X wouldn't take with 422 and X's reason on the field, such as platformSettings.adSet.bidAmount. What's still to fill in is saved and listed by GET /launches/{id}/publish, which checks everything X would: X has no test run of its own.
  • An ad is the launch's own: its text is the Post text, 280 characters with a link counting as 23, and its media, headline, link and button decide what X shows. settings.utm is added to each link as it's written, since X fills in no values.
  • GET /platforms/x/targeting searches X's audience values with facet set to one of the spec's targeting types, q and adAccountId. GET /platforms/x/conversions?adAccountId= lists the ad account's conversion events.
  • POST /platforms/x/audience-estimate with adAccountId and an ad group's audience asks X how many people it reaches (min, max; estimable is false for an audience of only locations, age, gender, language and devices). GET /platforms/x/ad-previews?adId= takes up to 25 ads, by their Pluto or X IDs, and answers X's own preview of each one's Post. To an API key both answer withheld: true with the numbers and the preview null, and X isn't asked: the estimate and the previews show in Pluto.
  • The synced campaigns, ad groups and ads are at GET /platforms/x/campaigns, /ad-sets and /ads. POST /platforms/x/imports brings campaigns in as launches (dryRun only reviews them), and GET /platforms/x/imports/{id} reports on it.
  • X's terms keep what Pluto reads from X inside Pluto. In an answer to an API key or an agent, a field holding what X reports (a name, a status, a figure) is null, and withheld beside it is true: X results show in Pluto. IDs, your launches and drafts, and the outcome of what you asked Pluto to do answer as always.
  • Live changes use the same routes as on Meta. An X ad can't be edited in place: POST /ads/{id}/status with PAUSED removes the ad from its ad group on X and ACTIVE adds the same Post again, and a pending change to its text, media, headline, link, button or cards replaces the ad on X when it's published. GET /launches/{id}/revisions says so on that change.
Create an X launch
curl -s "$PLUTO_API/launches" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-x-2026" \
  -d '{
    "name": "Spring sale",
    "platform": "x",
    "adAccountId": "18ce54d4x5t",
    "settings": {
      "primaryTexts": ["Spring is here"],
      "headlines": ["Shop the spring sale"],
      "websiteUrl": "https://example.com/spring"
    },
    "platformSettings": {
      "campaign": { "objective": "WEBSITE_CLICKS", "fundingSource": "lygyi", "dailyBudget": "100.00" },
      "adSet": {
        "identity": "1500000000000000001",
        "dailyBudget": "40.00",
        "audience": { "locations": [{ "id": "96683cc9126741d1", "name": "United States" }] }
      }
    }
  }'

X's defaults and settings templates use the same routes with x as the platform:

  • GET /defaults/x answers campaign and adSet in X's keys (the table above), launch with the workspace's X settings (utm, replies, leadSync) and accounts with each X ad account's defaults, keyed by its ID.
  • PATCH /defaults/x/campaign and /ad-set take the keys every X ad account shares. fundingSource, identity, conversionEvent, leadForm and the dates belong to one launch or ad account and answer 422, and so do the values each ad account keeps (purchaseOrderNumber, iosAppId, androidAppId, advertiserDomain, categories, trackingTags): set those per ad account.
  • PATCH /defaults/x/accounts/{accountId} takes settings with the keys to change for that ad account (identity, fundingSource, conversionEvent, purchaseOrderNumber, iosAppId, androidAppId, advertiserDomain, categories, trackingTags), and DELETE on the same address clears them. The X account and funding source must be the ad account's own. A new launch on the ad account takes them where it has none of its own. X's ad accounts share one version in accounts.
  • PATCH /defaults/x/launch takes utm (written out: X fills no values in a link, so {{...}} is refused), replies and leadSync. With replies off, replies to the workspace's ad Posts aren't read (each read costs X API credits). With leadSync off, leads aren't read, and lead forms still work.
  • POST /setting-templates with "platform": "x" holds campaign or ad group keys, never what names one ad account's objects. from saves an X ad group or campaign without them. campaignTemplateId on POST /launches and templateId on POST /launches/{id}/ad-sets start from one, and POST /setting-templates/{id}/apply applies one to X ad groups or launches.
  • GET /platforms/x/account-settings?adAccountId= reads an ad account's tax settings, your contact settings and its apps from X. Like everything X reports, the values are null with "withheld": true outside the app.

X's terms keep what Pluto Ads reads from X inside the app (policy.dataLeavesUi is false on GET /platforms), so the API tells you what there is and never the figures:

  • GET /analytics/insights?platform=x answers the platform, period, labels and import state, with metrics, byCurrency, breakdown and definedMetrics null, "withheld": true and "note": "X results show in Pluto.". X's numbers use the ad account's days (dayBasis is account) and count each conversion in its conversion event's windows (attributionBasis is conversionEvent), so attribution is null.
  • GET /changes?platform=x lists every change. A change Pluto made (source: pluto) carries its values; a change found on X (source: platform) has from, to, its description and the object's name left out and "withheld": true. What changed, when and the X IDs stay.
  • GET /analytics/segments?platform=x answers "rows": null and "withheld": true.
  • POST /analytics/refresh with "platform": "x" imports the last two days now, as for every platform.

X's numbers are kept for 90 days and deleted when X is disconnected.

On X, lead forms and replies use the same routes with "platform": "x":

  • Lead forms. POST /leads/forms creates a form on an X ad account: adAccountId, name, purpose (why you collect the details, shown on the form), fields (X's field keys such as EMAIL and FULL_NAME, each once, at least one not optional), privacyPolicy (url starting with https://, and companyName), and optionally introduction and finalPage. PATCH /leads/forms/{id} changes what the body names; fields, privacyPolicy, introduction and finalPage are each replaced whole. DELETE /leads/forms/{id} archives the form, which X can't undo. Each returns 202 with a job, and X's rules are checked first: a 422 names the field.
  • Leads. X sends no lead webhook, so Pluto Ads reads new leads from X every 15 minutes, or when you call POST /leads/sync with "platform": "x". X hands leads to the ad account's Account administrator only: when the connected X user has another role, access.lastError says so and the forms are still listed.
  • Replies. On X a comment is a reply. GET /social/comments?platform=x lists the replies to your ads' Posts; POST /social/comments/{id}/hide, /unhide and /replies hide, show and answer one as the connected X account, on ads that run as that account. X doesn't let anyone delete someone else's reply, so DELETE /social/comments/{id} takes only your own. A reply is written by a person: a reply sent by an agent or an MCP client is refused, because X needs to approve AI-written replies first.
  • What stays in Pluto Ads. X's terms keep what it reports inside Pluto Ads' own app. Through the API, a lead, a form and a reply answer with their IDs, times and what Pluto Ads did, with withheld: true: a lead's answers, a form's name and questions, and a reply's text are null or empty. Open Pluto Ads to read them. Pluto Ads keeps what it read from X for 90 days at most and deletes it when you disconnect X.
  • X API credits. Reading and answering replies costs X API credits. access.credits on the replies list shows what the workspace used this month (spentUsd) against its allowance, and attention holds one line when the allowance runs low: replies are then read less often, and from 75% only when you ask.

Pluto Profit

With Pluto Profit connected, your code can read whether the store's ads make money. Each workspace connects one store, and Pluto Ads only reads from Pluto Profit: it never changes anything there.

  • GET /profit/summary has the store's profit for a period, GET /profit/products what each product left after its costs and the ad spend allocated to it, and GET /profit/ads an estimate per Meta ad, ad set or campaign. Pass since and until as days in the store's timezone, at most 366 days apart.
  • Money is decimal strings: store and product figures in the store's currency, ad estimates in each ad account's currency. A value Pluto Profit can't compute, for example because a cost is missing, is null. It never means zero.
  • Pluto Profit reports profit per store and per product, not per ad. GET /profit/ads estimates it from the store's break-even ROAS and the purchase value Meta attributes to each ad, and every answer says so with estimate: true and its basis.
  • GET /integrations/pluto-profit has the connection and how current the store's data is. Without a working connection, the profit routes answer 409.
  • Admins connect. POST /integrations/pluto-profit/authorize returns an approval URL for a person to open in their browser, so it needs a credential that acts for a person; an API key gets 403. To connect with a Pluto Profit API key instead, use POST /integrations/pluto-profit/connect.
  • Guests never see profit.

Webhooks

A webhook sends a signed POST to your HTTPS endpoint when something changes in the workspace. Admins create them in SettingsAPI (Settings, then API) or with POST /webhooks. The signing secret is shown once.

Delivery
POST /hooks/pluto HTTP/1.1
Host: hooks.brevanne.com
Content-Type: application/json
User-Agent: PlutoAds-Webhooks/1
Pluto-Event: launch.changed
Pluto-Delivery: 01a0d7ea-73c8-7141-88fc-ca7e0a0f499b
Pluto-Signature: t=1790613261,v1=b2715e3196cd794c2f5da6d1d7d6265311e548dbee524ee6af3dfc9fb2a52034

{"id":"cbc4a711-9e0b-5c60-8991-f6b58af28200","event":"launch.changed","workspaceId":"01a0d7e5-acb8-7176-a698-b6947a8016fe","occurredAt":"2026-09-28T16:34:21Z","data":{"launchId":"01a0d8da-b21b-741f-9bdf-e0d0a8846c39","version":8}}

The payload names what changed. Read the current state through the API. Delivery is at least once, so skip an id you've already handled.

Verify the signature. Pluto-Signature is t=<unix seconds>,v1=<hex HMAC-SHA256>, computed with the whole whsec_... secret over <t>.<raw body>. Check it over the raw bytes, before parsing, and reject old timestamps.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact bytes received (a Buffer), before any JSON parsing.
export function verifyPlutoSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  const received = Buffer.from(parts.v1, "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Deliveries. Answer with any 2xx within 10 seconds. Anything else is retried after 30 seconds, 2, 10 and 30 minutes, then 1, 2 and 4 hours: 8 attempts in all. Each webhook's deliveries and their responses are in the app and at GET /webhooks/{id}/deliveries.

Who it answers to. A webhook delivers only while the person accountable for it may manage webhooks in the workspace: the person who created it, or for one an API key or agent created, that key's or agent's person while it still works. If their role stops including it, or they lose access, nothing is sent, retries of earlier events included, and GET /webhooks shows delivering: false with notDelivering saying why. It starts again by itself once they may manage webhooks again. Events in between aren't sent later.

Events. Subscribe to 1 to 50 events, or to * for every event, including ones added later. GET /webhooks/events lists them with a description each.

EventsWhen they fire
launch.changed, launch.deletedA launch or its settings changed, or a draft was deleted
launch.published, launch.publish_failedPublishing finished, or stopped with failed items
ad_set.changed, ad.changed, ad.deletedAn ad set or ad was created, changed, moved, deleted or archived
ad.review_changedThe ad platform's review of a published ad changed
meta.campaign.status_changed, meta.ad_set.status_changed, meta.ad.status_changedA status in Meta changed, including changes made in Ads Manager
meta.object.changedSomeone other than Pluto (a person in Ads Manager or another app) changed a campaign, ad set, ad or the ad account's spending limit in Meta: field, from, to, currency and who (changedBy)
campaign.status_changed, ad_set.status_changed, ad.status_changed, ad_object.changedThe same status changes and outside changes under platform-neutral names, with the platform in platform. Meta sends both.
metric.threshold_crossed, budget.spentA metric or budget crossed a threshold set in a loop
comment.created, comment.updated, comment.deleted, comment.restored, comment.resolved, comment.reopenedYour team's comments on ads
social.comment.createdSomeone commented on the post an ad runs as
lead.receivedSomeone submitted a lead form on a connected Page, or one of an X ad account's lead forms: on X the event carries IDs and times, and the form's name stays in Pluto Ads. platform names the ad platform when it isn't Meta
media.uploadedAn image or video is ready to use
workflow.changedReview statuses, tags, copy templates or country groups changed
integration.changedA connection was connected, synced or needs attention
job.completed, job.failed, job.cancelledLong-running work finished

POST /webhooks/{id}/test sends a webhook.test event, and POST /webhooks/{id}/rotate-secret replaces the secret at once. A workspace can have up to 20 webhooks. A webhook stops for good when the person who created it, or whose key or agent did, loses access to the workspace: suspended, removed or gone.

Audit log

Every change people, agents, loops and keys made, with who did it, the person it was for, where it came from and who approved it. The audit log comes with Business and Enterprise (402 plan_limit on other plans).

  • GET /audit-log is the workspace's log, for its admins. A credential needs admin.
  • GET /organizations/{id}/audit-log is the organization's: its plan, billing, credits and limits, members, invitations and credentials, whichever workspace the change came from. For the organization's owners and admins. A credential needs the organization scope.
  • Both take the same filters: actorKind, actorId, person, origin, originId, loopId, targetType, targetId, action (exact, or a prefix ending in .), commandId (the Idempotency-Key a change was sent with), since, until and q. They're newest first, or order=oldest, a page at a time with after.
  • Each entry has a summary sentence, and detail with what changed where it says more: before and after, changes, a reason, a role, scopes, an amount and currency, a plan, and the IDs it touched. detail never holds a secret, and has an email only on an entry about that invitation or person. q finds words in names, the action and detail, never in anything an entry doesn't show.
  • requestId names the request or tool call an entry came from: the x-request-id the API answered it with. Entries recorded before requests were kept have none.

Audit log exports

Export the log as CSV with POST /audit-log/exports, or POST /organizations/{id}/audit-log/exports for the organization's from one of its workspaces. The body takes the list's filters and gzip (true for .csv.gz), and the export runs in the background:

curl
curl -s -X POST "$PLUTO_API/audit-log/exports" \
  -H "Authorization: Bearer $PLUTO_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: audit-q3" \
  -d '{"since": "2026-07-01T00:00:00Z", "until": "2026-10-01T00:00:00Z", "gzip": true}'
  • It answers 202 with the export: id, jobId, status (queued, running, done or failed), rowsTotal once the entries are counted and rowsWritten as they're written. Asking again with the same filters while one is queued or running returns that one.
  • Follow it with GET /audit-log/exports/{id}, or the job with GET /jobs/{id}. Once it's done, the export has downloadUrl, a link to the file for 15 minutes. Read the export again for a new link.
  • Downloads end 7 days after the export was written (expiresAt).
  • The person who asked gets an Inbox notice when it's ready. When it runs longer than 30 seconds or holds more than 250,000 entries, or the app's page that asked for it was left before it was ready (emailWhenReady), they get an email at their account's address too, with a link to sign in and download it. An export that fails says so in the Inbox, never by email.
  • The file holds the entries as they were when the export was asked for, newest first unless order is oldest. Each export is in the audit log itself: audit_log.export_requested and audit_log.exported.

The columns, in this order (new ones only ever come at the end):

ColumnWhat it holds
idThe entry's ID
timeWhen it happened, ISO 8601 in UTC with microseconds: 2026-11-04T10:15:02.123456Z
workspace_id, organization_idWhere it happened; organization_id on changes to the organization
actionThe stable action name, such as live.budget_changed
summaryThe sentence the audit log page shows
actor_kind, actor_id, actor_nameWho acted: person, api_key, agent or system
on_behalf_of_id, on_behalf_of_nameThe person accountable: themself, the person an agent acts for, a key's creator
credential_kind, credential_id, credential_nameThe credential it came through: api_key, agent_client or agent_connection (empty for people and Pluto)
origin, origin_idWhere it came from (app, api_key, mcp, agent_chat, loop, system), and the chat or loop run
approved_by_id, approved_by_nameWho approved it, if someone did
target_type, target_id, target_nameWhat it changed
detailThe entry's detail as JSON, empty when it has none
command_id, request_idThe command (its Idempotency-Key) and the request it came from

The file starts with a UTF-8 byte order mark, so Excel reads accented and non-Latin letters correctly. A program reading the file skips the mark: in Python, open it with encoding="utf-8-sig". Cells follow RFC 4180, and lines end in CRLF. A number, such as a Meta ID in target_id, is written as it is; other text is always quoted, and an empty cell is empty. So that no spreadsheet runs a cell as a formula, whatever its list separator, a ' goes in front of a =, +, -, @, tab or carriage return that starts a cell, or that follows a comma, semicolon, tab or line break inside one, even after spaces or quotes: x;'=HYPERLINK(...). In detail, such a character is written as its JSON escape instead (= as \u003d), so detail is always the same JSON.

Workspace exports

Export a workspace's launches, ad sets and ads as CSV in the background with POST /organizations/{id}/workspaces/{workspace_id}/exports (gzip: true for .csv.gz). It needs organization admin access (a credential needs the organization scope), for any workspace of the organization, also an archived one or one scheduled for deletion, and runs in the workspace your credential works in, which must be an active one of the same organization (409 otherwise):

curl
curl -s -X POST "$PLUTO_API/organizations/$ORGANIZATION/workspaces/$WORKSPACE/exports" \
  -H "Authorization: Bearer $PLUTO_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: export-brevanne" -d '{}'
  • It answers 202 with the export (kind: "workspace"): id, jobId, status, rowsTotal once the rows are counted and rowsWritten as they're written. Asking again for the same workspace while its export is queued or running returns that one.
  • Follow it with GET /exports/{id}, or the job with GET /jobs/{id}. Once it's done, the export has downloadUrl, a link to the file for 15 minutes; downloads end 7 days later (expiresAt).
  • The person who asked gets an Inbox notice when it's ready, and an email when it ran longer than 30 seconds or holds more than 250,000 rows, or the app's page that asked for it was left before it was ready (emailWhenReady). An export that fails says so in the Inbox, never by email. Once the file is written, the export is recorded in the exported workspace's audit log (workspace.exported).
  • The file is the one GET /organizations/{id}/workspaces/{workspace_id}/export/ads.csv streams: the same columns, the same order and the same CSV rules as the audit log's (a byte order mark first). The media originals stay a streamed download, GET .../export/media.zip.

Usage exports

Export the organization's usage events as CSV in the background with POST /organizations/{id}/usage/exports. The body takes the events list's filters (period, or from and to; workspaceId, userId, source, loopId, agentId, model, q), bom and gzip. It comes with Business; members export their own usage, and whoever can view the organization's billing exports everyone's. It runs in the workspace your credential works in, an active one of the organization:

curl
curl -s -X POST "$PLUTO_API/organizations/$ORGANIZATION/usage/exports" \
  -H "Authorization: Bearer $PLUTO_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: usage-october" -d '{"period": "previous"}'
  • It answers 202 with the export (kind: "usage"), followed with GET /exports/{id} or GET /jobs/{id} as a workspace export is: rowsWritten of rowsTotal, then downloadUrl once it's done, for 7 days. Asking again with the same filters while one runs returns that one.
  • The file is what GET /organizations/{id}/usage/export streams: the same columns, the same events, oldest first. It has no byte order mark unless you ask for one with bom: true, for a person opening it in a spreadsheet.
  • The person who asked gets an Inbox notice when it's ready, and an email when it ran longer than 30 seconds or holds more than 250,000 events, or the app's page that asked for it was left before it was ready. Once the file is written, the organization's audit log records it (billing.usage_exported).

Attach files to Agent messages

Files attached to an Agent message are kept apart from the media library: they never show up there. They're private to the person whose chat it is, so they need a person's session or an agent acting for one (API keys get 403). Upload in three steps:

  1. POST /workspaces/{id}/chat-files with name, contentType and sizeBytes. The answer is 201 with the file (uploading) and an upload: a url, method (PUT) and headers.
  2. PUT the bytes to upload.url with exactly those headers.
  3. POST /workspaces/{id}/chat-files/{fileId}/complete. The bytes are checked and the file is prepared for the Agent: processing, then ready. Poll GET /workspaces/{id}/chat-files/{fileId} until it's ready or failed (with an error whose message you can show as it is).
Attach a PDF
curl -s -X POST "$PLUTO_API/workspaces/$WORKSPACE/chat-files" \
  -H "Authorization: Bearer $PLUTO_TOKEN" -H "Idempotency-Key: brief-q4-pdf" -H "Content-Type: application/json" \
  -d '{"name": "brief.pdf", "contentType": "application/pdf", "sizeBytes": 482113}'
KindTypesUp to
imagePNG, JPEG, WebP, GIF, HEIC, HEIF30 MB
pdfPDF100 MB
document, presentationWord (.docx), PowerPoint (.pptx)100 MB
spreadsheetExcel (.xlsx), CSV, TSV50 MB
text, codePlain text, Markdown, JSON, XML, YAML, HTML and source code10 MB
audioMP3, M4A, WAV, OGG, WebM, FLAC, up to 2 hours200 MB
videoMP4, MOV2 GB
archiveZIP, up to 200 files and 500 MB unpacked200 MB

Send ready files with a message: POST /agent/chats/{chatId}/messages with their IDs in context.fileIds, next to text. Media library items go in context.mediaIds. A message carries up to 20 files in all. A file that's still being prepared is a 409, so wait for ready. A file that failed, or that isn't yours, is a 422.

Ask about the PDF
curl -N -X POST "$PLUTO_API/agent/chats/$CHAT/messages" \
  -H "Authorization: Bearer $PLUTO_TOKEN" -H "Idempotency-Key: ask-brief-q4" -H "Content-Type: application/json" \
  -d '{"text": "What budget does this brief ask for?", "context": {"fileIds": ["'$FILE'"]}}'

The message comes back with its attachments. Each has a name and kind, and either a fileId with sizeBytes, contentType, pageCount and previewUrl (a path on the app's origin that redirects to a thumbnail, when the file has one), or a mediaId for a media library item.

A file that can't be attached is a 422 with code invalid, a reason (unsupported_type, too_large, empty or bad_name) and a message such as "This file is too large. The limit is 30 MB." A new file must fit your organization's storage, like media (402 plan_limit), and starting uploads is limited per person (429, see rate limits).

  • previewUrl (and GET .../preview) answers a thumbnail (a JPEG that never changes for the file, so browsers keep it): images, videos, the first page of a PDF, and Office files that saved one. GET .../content redirects to the original.
  • pageCount is set for PDFs, Word documents and presentations; durationMs for videos and audio.
  • A zip's files are listed in children, each with its own status. Files inside a zip inside the zip aren't opened, and a zip whose files don't fit your storage fails with a message saying so.
  • Attached files count toward your organization's storage from the moment the upload starts. They're never deleted automatically. An upload that isn't completed within two hours fails, and stops counting if its bytes never arrived.

Editing a message

Edit any of your own messages in a chat and continue from it, as in the app: POST /agent/chats/{chatId}/messages/{messageId}/edit, with the same body as sending a message. It answers with the same event stream.

  • An answer that's still running stops first, as with POST /agent/chats/{chatId}/stop. What it already did stays done, and its usage stays billed.
  • The new text becomes the message's next version. Everything after the message leaves the conversation, and Agent answers with the history up to the edited message. Attachments in context replace the message's.
  • Nothing is deleted. Every message has version and versions (both 1 unless it was edited). GET /agent/chats/{chatId}/messages/{messageId}/versions lists a message's versions, and POST /agent/chats/{chatId}/messages/{messageId}/version with {"version": 1} switches to another one. Each version keeps the answers that followed it.
  • Only the person who sent a message can edit it (403). An answer that doesn't stop in time is a 409, so try again. Switching versions while an answer runs is a 409 too.
  • Editing never refunds or re-charges earlier answers. The new answer is billed like any other.
  • MCP: edit_agent_chat_message, list_agent_chat_message_versions and select_agent_chat_message_version.
Edit a question and continue
curl -N -X POST "$PLUTO_API/agent/chats/$CHAT/messages/$MESSAGE/edit" \
  -H "Authorization: Bearer $PLUTO_TOKEN" -H "Idempotency-Key: edit-q2" -H "Content-Type: application/json" \
  -d '{"text": "Which ad set spent the most last week?"}'

Retrying an answer

Run any answer again, not only the last one, as in the app: POST /agent/chats/{chatId}/messages/{messageId}/retry with the answer's ID. It answers with the same event stream, starting with the new version.

  • The new answer becomes the answer's next version. The answer and everything after it leave the conversation and stay with the earlier version. Nothing is deleted. GET /agent/chats/{chatId}/messages/{messageId}/versions and POST /agent/chats/{chatId}/messages/{messageId}/version work on answers too.
  • Agent answers the question before it again, with the files it had, as the person who asked it.
  • Send {"model": "...", "effort": "..."} to run it on another model (the chat keeps it from then on), or no body.
  • A question's ID is a 422: edit the question instead. While an answer runs, or for an answer that isn't in the conversation now, it's a 409.
  • Earlier versions keep their usage. The new answer is billed like any other.
  • POST /agent/chats/{chatId}/retry still runs the last answer again in place when it failed or was stopped.

Questions and selections

When a wrong guess would cost something, Agent may ask before it acts. It asks one question with two to four choices, or proposes a list of options to confirm, such as the ad sets it would pause. Its answer then has status awaiting_user, with the question or the options in parts:

  • A question is a part with type question, its text and choices (id, label, description). Answer it with POST /agent/chats/{chatId}/parts/{partId}/answer and {"choiceId": "2"}.
  • A selection is a part with type selection, a title, options (id, label, detail) and the proposed option IDs. Confirm exactly the ones you keep with POST /agent/chats/{chatId}/parts/{partId}/select and {"optionIds": ["..."]}. An empty list confirms none.
  • Either becomes your next message, and Agent continues. Both answer with the same event stream as sending a message. The part then records your reply: answer and choiceId, or selected.
  • You can always reply in your own words with POST /agent/chats/{chatId}/messages instead. An open question then records your words as its answer.
  • A selection changes nothing by itself. Agent acts on what you confirmed with its usual tools, and asks for approval where it always does.
  • A question that was already answered, or a chat that moved on, is a 409.

Approvals sent to your Inbox

A member's Agent may propose an action their role leaves out. Proposed in their own chat, which nobody else opens, it goes to the Inbox of the workspace's members who hold what deciding it needs: an item with kind approval, the action as its title, who asked as its actor, and approval (id, status, decidedBy). It never holds the chat.

  • GET /agent/approvals/{id} is the approval's own card: its effect as the chat's card has it, capability, proposedBy, decidedBy, expiresAt, and canDecide while you hold capability and may use the Agent. Anyone it wasn't sent to gets a 404, the person who asked included.
  • POST /agent/approvals/{id}/decision with {"decision": "approve"}, or "reject" with an optional reason, decides it there and answers with the card. Approving runs the action once, as you. Without capability it's a 403 naming it, and approving a day after it was proposed is a 409 that runs nothing. Retried with the same Idempotency-Key, the decision is replayed.
  • The person who asked sees the outcome in their chat, and their answer continues.

While an answer streams

Besides the events described above, the stream sends stall when an answer seems stuck: messageId and stall, with a kind and since (when the silence began, in epoch milliseconds). no_first_byte means the model sent nothing for 10 seconds, silent_stream that an open stream sent nothing for 15 seconds, and silent_tool that a tool reported nothing for 45 seconds. The next stall event with stall null says it moves again. Stalls are never stored.

The answer's steps carry a category saying what kind of call each was: write (added something), edit (changed or removed something), read, list, search, or mcp with server naming the other Pluto product it called. Narration and thinking have none, and neither do steps from before it was recorded.

Web search in Agent answers

Agent searches the web and reads pages when a question needs it. Nothing turns it on or off per message.

  • The answer's steps include kind search (label "Searching the web", then "Searched the web"; detail is the query) and kind fetch (label "Reading example.com", then "Read example.com"; detail is the page's URL). tool is null for both. A step that failed has status failed.
  • The answer's sources lists the pages it used: url, title and site (the hostname without www.). Cited pages come first, in the order they were first cited, then pages it read without citing. Each URL appears once. sources is an empty list when the answer didn't use the web.
  • While an answer streams, a sources event carries messageId and the whole list so far. Replace what you have. The done event's message and GET /agent/chats/{chatId} return the final list.
  • Each search uses credits. See Models and rates.

Charts and tables in Agent answers

Agent can show a chart or a table in its answer, drawn by the app. Agent sends the data. Every value has to come from what Pluto's tools returned in the chat, and a chart with a value Pluto can't find there is never shown.

  • The answer's parts lists them in the order shown, each with type chart, an id and a kind: line, bar, horizontal-bar, stacked-bar, stacked-area, donut, funnel, combo, simple-bar, simple-normalized, spark-line, spark-bar or table. A chart has data, a list of series (name, and data with each point's key and value; value is null where there is none). A combo chart has groups, and a table has columns and rows. title, description, valueFormat (style decimal, percent or currency with currency, notation, fraction digits, unit), xAxis and yAxis say how it reads. Percent values are percentages: 12.5 is 12.5 %.
  • parts is an empty list for most answers.
  • What the Agent writes before ads or a chart it shows is a text part (id and text, Markdown), in parts before the cards; the message's text is what it wrote after them.
  • While an answer streams, a part event carries messageId and the part. A part with an id you already have replaces it. The done event's message and GET /agent/chats/{chatId} return every part.
  • A chart shows at most 7 series plus one named "Other", 60 points per bar series, 150 per line series and a table 50 rows. Agent sums up larger data first and says how.

Ads in Agent answers

Agent can show ads in its answer as cards. It names the ads, and Pluto reads each one in your workspace: an ad of another workspace is never shown.

  • Each is a part with type ads, an id, an optional title, the period its numbers cover (since, until, and preset such as last_30_days), and items, the ads in the order shown.
  • An item has the ad's name, an optional label (one line over its card), metaAdId, the Pluto ad it opens (launchId and adId, null when no launch manages it) and adsManagerUrl.
  • media is its media library file (id, kind image or video, durationMs), or null without one. Read the file with GET /media/{id}/preview?variant=preview (its picture, the JPEG itself once the file is ready) or variant=original (a redirect to a short-lived URL).
  • clip is the part of a video the card plays: startMs, endMs and source. hook is where Creative Memory found the hook, start is its first 5 seconds and asked is a moment Agent chose. null plays the whole video.
  • metrics has the ad's currency and its spend, roas and cpa for the period as decimal strings, each null when Meta reported none. It is null when the ad had no delivery in the period.
  • An answer shows up to 12 ads per part. Like charts, a part streams as a part event.

Good to know

  • Long work, like publishing or importing, returns a job. Follow it with GET /jobs/{id}, or with webhooks. Nothing is live in Meta or LinkedIn or X until the job confirms it.
  • Canceling a job with POST /jobs/{id}/cancel, or retrying one with POST /jobs/{id}/retry, needs what its work needs as it runs: a live change what it changes (delivery:write to pause or resume, budgets:write for budgets, bids and dates, ads:delete to delete), ads:publish for publishing and every other change to what runs, integrations:write and budgets:write for a spending limit, and launches:write for anything else. Queued work checks the same again before each item runs, on every platform: what its person can no longer do fails that item and is in the audit log.
  • Reactions, following, the Inbox and view preferences act for a person. API keys get 403 there.
  • Agent model IDs come from GET /agent/models. pluto always runs the latest Pluto version; pluto-1 stays on Pluto 1. PUT /agent/models/visibility sets which models a person's picker shows.
  • Browser requests with a session are checked for the app's origin. Keys and tokens have no origin rule.
  • An ad set's settings can be sent as one flat settings object (POST /launches/{id}/ad-sets, PATCH /ad-sets/{id}): locations, ages, gender, audience, performance goal, pixel and event, attribution, budget, cost or bid cap, ROAS goal, devices, placements, delivery and the EU advertiser, with start and end for the schedule. budget and bidAmount need currency, which must be the ad account's: amounts are never converted.
  • newCampaign on PATCH /launches/{id} merges key by key, so {"bidStrategy": "COST_CAP"} changes only the bid strategy.
  • Values the editor doesn't offer (a gender, placement, attribution window or call to action that isn't on the list, an amount that isn't a decimal) are a 422 naming the field.
  • Agents can use all of this through the MCP server.