Competitors
The in-app Agent: chats with streamed answers, approvals for publish and admin actions, metered in the organization's usage (see Billing).
List researched competitors
The workspace's competitors researched so far, the latest first, with how many of their ads are kept, running and read by Creative Memory. Also in MCP as part of get_competitor_ads.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- The workspace's competitors.
curl "$PLUTO_API/competitors" \
-H "Authorization: Bearer $PLUTO_KEY"List competitors' ads
Researched competitors' ads with what Creative Memory found in them, their funnel stage, angles and why, their Ad Library link and a short-lived address of Pluto's copy of their picture. ids is a comma-separated list; the other filters are get_competitor_ads's. Running ads first, the longest-running first. Also in MCP as get_competitor_ads.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
advertiserId | string | Optional | A researched competitor. |
pageId | string | Optional | Or its Facebook Page ID. |
advertiser | string | Optional | Or its name or domain as researched. |
ids | string | Optional | These ads only, comma-separated, up to 100. |
stage | string | Optional | top, middle or bottom. |
angle | string | Optional | An angle the ads show (discount, social_proof, problem, ...). |
active | string | Optional | true: running now; false: stopped. |
analyzed | string | Optional | true: Creative Memory's findings ready. |
minDays | string | Optional | Running at least this many days. |
format | string | Optional | The Library's format: image, video, carousel, dco, ... |
q | string | Optional | Words in the copy. |
limit | string | Optional | Ads per page, 1-50 (default 20). |
after | string | Optional | The previous page's nextAfter. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
advertisers- The workspace's competitors, when none was named.
items- This page.
nextAfter- Pass as the cursor for the next page; null at the end.
curl "$PLUTO_API/competitors/ads" \
-H "Authorization: Bearer $PLUTO_KEY"Run competitor research
Finds a competitor's running ads in Meta's public Ad Library by its name, Facebook Page ID or shop's domain in one country, keeps them in the workspace with their images and videos, and has Creative Memory read the main file of the longest-running ones (analyze, default true), charged in the organization's credits as the workspace's own analyses are (50 per image, 250 per started minute of video, its first three minutes) and never ahead of its own files. Answers at once with what's ready; the rest follows in GET /competitors/ads and GET /competitors/{id}/funnel. A site's refusal is answered in library.blocked with the address to open. Also in MCP as research_competitor.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
advertiser- The brand as it advertises (its Facebook Page's name), up to 100 characters.
analyze- Give their main files to Creative Memory (default true; uses credits).
country- Where its ads run: a two-letter country code (US, DE, GB) or ALL.
domain- Its shop's domain (shop.example): found among the sites its ads link to.
maxAds- Running ads to read, 1-50 (default 30).
maxAnalyses- Ads whose main file Creative Memory reads, the longest-running first, 0-30 (default 10).
pageId- Its numeric Facebook Page ID, when known (from candidates or the Ad Library).
Response
ads- Its longest-running ads.
advertiser- The competitor: id, name, pageId, domain, country, libraryUrl (its ads in the public Ad Library), researchedAt, ads, activeAds, analyzedAds.
analyses- Creative Memory: queued (now), inProgress, ready, waiting (for credits or Creative Memory, with
reason), failed, maxCredits (the most the queued files use). candidates- When none matched for sure.
found- Whether the advertiser was found.
library- How the Library was read: source (library_site or library_api), url (the public address), shownTotal, blocked (why the site didn't answer; null when it did), ms, cached.
note- What the answer is and what comes next.
read- Running ads read now.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402The organization is read-only (only with
analyze). - 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/competitors/research" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f40c4944-5e7f-486d-9ae3-b75888ec0867" \
-H "Content-Type: application/json" \
-d '{
"advertiser": "Brevanne",
"analyze": true,
"country": "US",
"domain": "brevanne.myshopify.com",
"maxAds": 3,
"maxAnalyses": 3,
"pageId": "229657833239852"
}'Get a competitor's funnel
Each running ad (includeInactive for stopped ones too) read as top, middle or bottom of the funnel from its hook, offer, call to action, landing page and what Creative Memory found in it; per stage the ads, share, dominant hooks, angles, offers, calls to action, landing pages and formats; where the ads send people; the longest-running ads; and the angles they use that the workspace's own Creative Memory rarely shows, and the reverse (compare, default true). Also in MCP as analyze_competitor_funnel.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The competitor's ID. |
compare | string | Optional | Compare with the workspace's own Creative Memory (default true). |
includeInactive | string | Optional | Stopped ads too (default: running ones only). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
ads- Ads read.
advertiser- The competitor: id, name, pageId, domain, country, libraryUrl (its ads in the public Ad Library), researchedAt, ads, activeAds, analyzedAds.
analyzed- Of those, with Creative Memory's findings.
byAd- Each ad's stage, up to 60.
gaps- {ownAnalyzed, theyUse [{angle, theirs, yours}], onlyYou [...], note}: shares in percent.
landingFlow- Kinds of landing page.
note- How to read it.
pending- Still being read by Creative Memory.
stages- Top, middle and bottom.
topPages- The pages linked most.
winners- The longest-running ads.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/competitors/c1bbc5f7-c690-45f1-acca-4911cfce6445/funnel" \
-H "Authorization: Bearer $PLUTO_KEY"