Analytics
Ad performance from Meta and LinkedIn and X, and the dashboard layout.
Get auction insights
The other advertisers' display domains that took part in the same auctions as an ad account, or as the campaigns, ad groups or keywords you name, with impression share, overlap rate, position above rate, top of page rate, absolute top of page rate and outranking share over the period, read live from a platform that offers auction insights through its API (GET /platforms says which platforms a workspace has; one without them answers 422 on platform). One ad account at a time, never added across accounts; nothing is summed or averaged by Pluto. Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Optional | A platform from GET /platforms. |
since | string | Optional | First day (YYYY-MM-DD), in the ad account's time zone, within the days the platform keeps (retentionDays). |
until | string | Optional | Last day (YYYY-MM-DD). |
adAccountId | string | Optional | The ad account; the first one reachable when left out. |
level | string | Optional | account (default), campaign, ad_group or keyword. |
id | string | Optional | A campaign, ad group or keyword ID from entities (up to 200, repeatable or comma-separated); none at account. |
segment | string | Optional | day, week, month, quarter, day_of_week or device (up to three, repeatable). |
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
accounts- The ad accounts to choose from.
accounts[].id- The platform's ID.
accounts[].name- Its name; null where the platform's terms keep it in Pluto's own app.
adAccountId- The ad account the insights are of (the first one reachable when none was named); null with none.
entities- The first page of the level's campaigns, ad groups or keywords of the ad account, by name; the rest by
GET /analytics/auction-insights/entitiesfromentitiesNext. entitiesNext- The
cursorofentities' next page; null when it holds them all. entitiesTruncated- More follow
entities' first page (entitiesNext). entries- One advertiser's display domain each, as the platform answered them. Empty where nothing was asked yet, where the platform has too few impressions to say, or where its terms keep the numbers in Pluto's own app (
withheld). entries[].absoluteTopOfPageRate- Absolute top of page rate (0 to 1).
entries[].displayDomain- The advertiser's display domain, as the platform wrote it.
entries[].impressionShare- Impression share: a share from 0 to 1, as decimal text.
entries[].outrankingShare- Outranking share: how often your ad ranked above its, or showed when its didn't (0 to 1).
entries[].overlapRate- Overlap rate: how often this domain's ad showed when yours did (0 to 1).
entries[].positionAboveRate- Position above rate: how often its ad showed above yours (0 to 1).
entries[].segmented- The same rates per combination of the segments asked; empty without segments.
entries[].segmented[].absoluteTopOfPageRate- Absolute top of page rate (0 to 1).
entries[].segmented[].impressionShare- Impression share: a share from 0 to 1, as decimal text.
entries[].segmented[].outrankingShare- Outranking share: how often your ad ranked above its, or showed when its didn't (0 to 1).
entries[].segmented[].overlapRate- Overlap rate: how often this domain's ad showed when yours did (0 to 1).
entries[].segmented[].positionAboveRate- Position above rate: how often its ad showed above yours (0 to 1).
entries[].segmented[].segments- One value per segment, in
segments' order. entries[].segmented[].topOfPageRate- Top of page rate (0 to 1).
entries[].topOfPageRate- Top of page rate (0 to 1).
ids- The campaigns, ad groups or keywords asked about.
levelaccount,campaign,ad_grouporkeyword.periodperiod.since- First day.
period.until- Last day.
platform- The platform the insights are of.
retentionDays- How many days back the platform keeps auction insights.
segments- How each
segmentedrow is split, in order. source- Who answered: the numbers are the platform's own.
usedImpressions- The share of impressions the entries were made from (0 to 1), as decimal text.
usedKeywords- How many keywords the entries were made from.
withheld- The platform's terms keep these numbers in Pluto's own app: they exist there, and asking again here gives the same answer.
curl "$PLUTO_API/analytics/auction-insights" \
-H "Authorization: Bearer $PLUTO_KEY"List insight choices
Every campaign, ad group or keyword of an ad account that auction insights can be asked about, a page at a time and searched by the words of their names (the campaign and ad group they're in, a keyword's match type), from Pluto's copy of the account's structure: nothing is ever left out. Changes nothing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Optional | A platform from GET /platforms that offers auction insights. |
adAccountId | string | Optional | The ad account; the first one reachable when left out. |
level | string | Optional | campaign (default), ad_group or keyword. |
search | string | Optional | Words that every result's names hold, in any order. |
cursor | string | Optional | The nextCursor of the page before. |
limit | string | Optional | Entities in a page (1-200, default 200). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
adAccountId- The ad account; null with none.
entities- This page, by name.
levelcampaign,ad_grouporkeyword.nextCursor- The next page's
cursor; null on the last page. platform- The platform.
curl "$PLUTO_API/analytics/auction-insights/entities" \
-H "Authorization: Bearer $PLUTO_KEY"Get the dashboard layout
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
sections, isDefault, version and defaultSections (what a reset restores).
curl "$PLUTO_API/analytics/dashboard" \
-H "Authorization: Bearer $PLUTO_KEY"Replace the dashboard layout
sections replaces the whole layout for everyone in the workspace: sections and cards left out are removed. There is no partial update. A stale expectedVersion is a 409 with the current layout; nothing is saved.
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
expectedVersion- The version you last read. A mismatch is a conflict that returns the current entity.
sections- Layout.
Response
The layout.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/analytics/dashboard" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 5d8150fe-d6a3-47b3-80a6-28e6d21a1fb9" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3,
"sections": [
{}
]
}'Restore the default layout
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
expectedVersion- Optional: the version you last read. A layout saved since then is a 409 with the current layout instead of being dropped.
Response
The layout.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/analytics/dashboard" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 92c6468d-2455-4a03-a18f-c2608f05ecd9" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 3
}'Get ad performance for a period
From ingested insights of one ad platform (platform; default: the platform of the launches, accounts, campaigns, ad sets or ads named, else the last-used connected platform), restated as the platform restates them. Filters repeat (campaignId=A&campaignId=B); totals are exact sums over every row in scope and never mix currencies. One platform per answer, or several with platforms, each answered on its own. metric, definitions, sort, limit and cursor shape the answer: only those metrics with their definitions, and the breakdown rows sorted and paged. Where a platform's terms keep its results inside Pluto's own app, the answer says so in withheldData and the Pluto-Withheld header. Another platform's answer carries platform and dayBasis (utc where it reports UTC days, account where the ad account's time zone days); where it counts each conversion in its conversion rule's or ad group's own windows, attribution is null and attributionBasis is conversionRule or adGroupSetting; settlingFrom is the first day it may still change.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
since | string | Optional | First day (YYYY-MM-DD) in each ad account's timezone. |
until | string | Optional | Last day, inclusive. |
attribution | string | Optional | 7d_click_1d_view (the ad set attribution setting, as in Ads Manager), 7d_click, 1d_click, 1d_view or 28d_click. Segment breakdowns and filters read Meta's default, 7d_click_1d_view. |
breakdown | string | Optional | launch, campaign, adSet or ad; or a segment. Meta: age, gender, ageGender, country, region, placement, publisherPlatform, impressionDevice, devicePlatform, hour, actionDevice, actionDestination, actionType, bodyAsset, titleAsset, imageAsset, videoAsset, callToActionAsset, linkUrlAsset, adFormatAsset or product (13 months back). Other platforms with segments: age, gender, country, region, hour, device, network, clickType, slot, conversionAction, searchTerm, keyword, asset, audience or dayOfWeek (from the daily facts). |
age | string | Optional | Only these age ranges (18-24, …, 65+; some platforms also undetermined); repeatable. Segment filters come from one breakdown at a time (on Meta age and gender together are one), and every figure is then the segments' own. |
gender | string | Optional | Meta: female, male or unknown; elsewhere female, male or undetermined; repeatable. |
ageGender | string | Optional | Meta: <age>|<gender>, e.g. 25-34|female; repeatable. |
country | string | Optional | ISO country code; repeatable. |
region | string | Optional | Meta: region as Meta names it; elsewhere the region's geo target ID; repeatable. |
placement | string | Optional | Meta: <platform>|<position>, e.g. instagram|reels; repeatable. |
publisherPlatform | string | Optional | Meta: facebook, instagram, audience_network, messenger or threads; repeatable. |
impressionDevice | string | Optional | Meta: device as Meta names it (iphone, android_smartphone, …); repeatable. |
devicePlatform | string | Optional | Meta: mobile_app, mobile_web or desktop; repeatable. |
hour | string | Optional | hour of the day in the ad account's time zone, 00 to 23; repeatable. |
actionDevice | string | Optional | Meta: the device an action happened on; repeatable. |
actionDestination | string | Optional | Meta: where an action happened; repeatable. |
bodyAsset | string | Optional | Meta: a dynamic or flexible creative's text asset ID; repeatable. |
titleAsset | string | Optional | Meta: headline asset ID; repeatable. |
imageAsset | string | Optional | Meta: image asset ID; repeatable. |
videoAsset | string | Optional | Meta: video asset ID; repeatable. |
callToActionAsset | string | Optional | Meta: call to action asset ID; repeatable. |
linkUrlAsset | string | Optional | Meta: link asset ID; repeatable. |
adFormatAsset | string | Optional | Meta: ad format asset; repeatable. |
format | string | Optional | Meta: the same as adFormatAsset. |
product | string | Optional | Meta: a catalog product as Meta reports product_id; repeatable. |
device | string | Optional | Where the platform reports it: mobile, desktop, tablet, connected_tv or other; repeatable. Other platforms' segment filters come from one breakdown at a time. |
network | string | Optional | Where the platform reports it: search, search_partners, content, youtube_search, youtube_watch, mixed, google_tv or unknown; repeatable. |
clickType | string | Optional | Where the platform reports it: the click type as the platform names it, lower case (url_clicks, call_tracking, sitelinks, …); repeatable. |
slot | string | Optional | Where the platform reports it: search_top, search_other, content, search_partner_top, search_partner_other, mixed or unknown; repeatable. |
conversionAction | string | Optional | Where the platform reports it: a conversion action's ID; only the conversion metrics are split by it; repeatable. |
searchTerm | string | Optional | Where the platform reports it: <search term>|<match type>, e.g. running shoes|broad; repeatable. |
keyword | string | Optional | Where the platform reports it: a keyword's criterion ID; repeatable. |
asset | string | Optional | Where the platform reports it: <asset ID>|<field type>, e.g. 123|headline; repeatable. |
audience | string | Optional | Where the platform reports it: an audience segment's criterion ID; repeatable. |
actionType | string | Optional | Meta: an action type whose action:<type>, action_value:<type> and cost_per_action:<type> every breakdown row carries; repeatable. |
series | string | Optional | An action metric (action:<type>, …) whose series actionMetrics carries; repeatable. |
platform | string | Optional | A platform from GET /platforms (default meta). Its ad account, campaign, ad set and ad IDs go in the ID filters. |
compare_since | string | Optional | Comparison period start. |
compare_until | string | Optional | Comparison period end. |
today | string | Optional | This device's today (YYYY-MM-DD) when since-until were picked counted from it (a preset): each ad account in view then reads those days counted from its own today, as its ads manager does. Accounts on one day just now read one period, and period is it. Accounts on different days (New York still on Nov 12 while Copenhagen is on Nov 13) each read their own: period stays as asked and accountPeriods lists each group's days. An ad account without a time zone reads the days as asked; without today every account does. |
preset | string | Optional | With today: the preset since-until are on that day: today, yesterday, last7days, last14days, last28days, last30days, last90days (today included), last_week (Monday first), last_month, last_quarter, last_year, mtd, qtd, ytd (also this_month, this_quarter, this_year). Today is each account's own today, the 1st of a month too; a rolling preset counts its days back from the account's today; a calendar one is the account's own calendar period. Without it, or when it doesn't name those days, the days say which preset they are (the first in this order, so the 1st of a month's single day is Today); days that are none are moved by as many days as the account is behind or ahead. |
comparison | string | Optional | With today: how compare_since-compare_until follow the period: previous_period (as many days just before) or previous_year (the same dates a year earlier); each account's comparison follows its own period so, with as many days. Without it the dates say which; any other comparison is read as its dates. |
interval | string | Optional | day (default), week (Monday first) or month: what one series point covers. Each point sums its days and computes ratios from those sums; the first and last points hold only the period's days. Reach and frequency have a daily series only. |
adAccountId | string | Optional | Repeatable. |
account | string | Optional | Ad account name; repeatable. |
campaignId | string | Optional | Repeatable. |
campaign | string | Optional | Campaign name; repeatable. |
adSetId | string | Optional | Repeatable. |
adSet | string | Optional | Ad set name; repeatable. |
adId | string | Optional | Repeatable. |
launchId | string | Optional | Repeatable. |
launch | string | Optional | Launch name; repeatable. |
currency | string | Optional | Only accounts in this ISO 4217 currency. |
platforms | string | Optional | Several platforms in one answer instead of platform, comma-separated or repeated (all: every connected platform): each answered on its own under byPlatform, read at once and never added together. |
metric | string | Optional | Only this metric (any ID of the platform's catalogue, action:<type> on Meta), everywhere metrics are, with its definition in definitions; repeatable. An ID the platform doesn't report is a 422 that names the closest IDs it has. |
definitions | string | Optional | true: each metric's definition in definitions (implied by metric). |
sort | string | Optional | With breakdown: order the rows by this metric, descending (-spend too); rows without a value come last. |
order | string | Optional | desc (default) or asc. |
limit | string | Optional | With breakdown: at most this many rows (1 to 1000); breakdown.rowsTotal counts every row in scope. |
cursor | string | Optional | The previous answer's breakdown.nextCursor, the rest of the query unchanged. |
thenBy | string | Optional | With breakdown: split every row again, by day, week or month, or (a breakdown by launch, campaign, ad set or ad) by a segment such as country, age or placement. 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. |
status | string | Optional | Only ads with this status in the platform's words (ACTIVE: delivering now, PAUSED), totals included; repeatable. |
labelId | string | Optional | Only the ads Pluto labelled with this label, totals included; repeatable. |
label | string | Optional | Only the ads Pluto labelled with a label of this name; repeatable. |
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
accountPeriods- With
today, when the ad accounts in view are on different days just now: per group of accounts on one day,accounts(their IDs),sinceanduntil(the days they read forperiod) andcomparisonPeriod(since, until, or null).periodstays as asked; a series point is its day, each account's day counted from the start of its own period (Today: New York's Nov 12 and Copenhagen's Nov 13 are one point), and a series runs longer thanperiodwhere a group's period is (on Dec 1 in Copenhagen, This month is all of New York's November). Reach and frequency stay one account's. Absent when every account readsperiod. actionMetrics- Meta: every action type it counted in the period, custom conversions included, as
action:<type>(the count) and, in one currency,action_value:<type>andcost_per_action:<type>:value,comparisonValue,change;seriesonly for those named inseries. attributionBasisconversionRulewhere each conversion counts in its conversion rule's windows,adGroupSettingwhere in its ad group's own windows.breakdowndimensionandrows(id,name,currency,metrics; an ad row on Meta alsorankings{ quality, engagementRate, conversionRate, asOf } as Meta labels them; a segment row its segment value inidand an asset's or product's text inname, andunattributedfor actions Meta reported without the breakdown's value). Meta:noteby region, product, actionDevice or actionDestination, which Meta splits no conversion off its own apps by (purchases, their value, carts, checkouts, landing page views: absent, never 0);incompleteby actionType andrankingsIncompleteby ad whilecoverage.history.fieldsCompleteFromis after the period's start. A campaign or ad set in Pluto (published from a launch, imported, or kept in sync) also haslaunchId, and an ad set not archived in Pluto itsplutoAdSetId; the ad set performance list's rows the same, withcampaignLaunchIdfor their campaign.byCurrencymetricsandactionMetricsper currency when mixed.byPlatform- With
platforms: each platform's own answer (this shape) by platform, besideplatforms,withheldPlatforms(whose terms keep their results in Pluto),refused(per platform{ message, problems }where it can't answer the question) andnote. Platforms are never added together. changeCoversperiodandcomparisonPeriod(each since, until): the days a change compares while one of the period isn't over yet, so a part of a day is never set against a whole one (the period's days that are over and as many of the comparison period's). Both null: no day of the period is over yet, so no metric has a change. Null when a change covers the whole periods or there's no comparison.comparisonIncomplete- The comparison period reaches back before the history every ad account in view holds (older days still importing; on Meta older than the 37 months it keeps, on another platform older than the days its terms let Pluto keep), or, on Meta with a segment filter or breakdown, outside the days its breakdown set covers (
coverage.breakdowns), so nothing is compared and no metric has a change. comparisonPeriod- since, until, or null.
coveragefrom,to(null without a period),state(importing,notImported,noDelivery,fresh),freshAsOf(least recent import among accounts that have imported; null only when none has),importing,importJobId,nextUpdateAt(when the next pull of the accounts in view is due), per-accountaccounts(freshAsOf,coveredThrough,lastError,importing,history:from(complete back to that day),complete(back to the 37 months Meta keeps),importing(older days still coming),coveredDays,totalDays,limit,nextAt,lastError; thenunreadDays: days Meta couldn't produce even in smaller requests, which keep the numbers they had until a later import reads them),notYetImported,missingAccounts(not imported through the period's end),historyover the accounts in view (from,complete,importing,incompleteAccounts: history not yet back to the period's start;fieldsCompleteFrom, also per account: the first day every field is in while older days are read again with the newer ones, action types, video plays, watch time and rankings) and, on Meta when breakdowns were read,breakdownsper breakdown set (from,through: the last day read to its end,readAt,complete: back to the 13 months Meta keeps,level:accountfor whole ad accounts oradfor a read narrowed to a campaign, ad set, ad or launch, whose segments cover the last 14 days,unreadDays: days Meta couldn't produce, which keep the numbers they had,unavailableAccounts:id,name,reason, ad accounts Meta refused it for, such as impression device before it's enabled on the account).currencies- Currencies in view. More than one: amounts are per currency in
byCurrencyand never added together. currency- ISO 4217; null when rows span several currencies.
dayBasisutcwhere the platform reports UTC days,accountwhere it reports the ad account's time zone days, on another platform's answer.definitions- With
definitions=trueormetric: per metric ID{ id, name, unit, aggregation, summable, perCurrency, lowerIsBetter }.unitis money, count, fraction, multiple or seconds;aggregationis sum, ratio (recomputed from the sums), weighted (by impressions) or window (the platform's own figure for exactly the period and object, like reach, frequency and unique clicks: never summed, so breakdown rows don't add up to it). freshness- How late the platform's numbers usually arrive, where it says:
metricsMinutes,reachMinutes. inProgressFrom- YYYY-MM-DD: the period's first day that isn't over yet in the time zone of every ad account in view (null when the period is over). From it on a series point holds only part of its days so far, or none yet.
intervalday,weekormonth: what one series point covers; a point'skeyis its first day in the period.metrics- Per metric:
value(decimal string; money in the account currency, ratios as fractions),series,comparisonValueandchange{ absolute, relative }against the comparison period. Ratios are recomputed per period from that period's sums, never averaged;relativeis a fraction and absent when the previous value is 0;changeis absent when either period has no value. While a day of the period isn't over yet (changeCovers),changecovers the days that are over and also carries the two values it is taken between,valueandcomparisonValueover those days; the metric's ownvalueandcomparisonValuestay the whole periods'. Metrics Meta reported nothing for are absent, never 0.incomplete: trueon Meta: the metric reads fields the ad accounts' older days are still being read again with (action types, video plays, watch time, engagement), and the period reaches beforecoverage.history.fieldsCompleteFrom. moneyBasis- Meta's answer: where its money comes from.
account: Meta's own figure for each ad account and day, in the attribution setting read, as Ads Manager shows it.ads: the sum of the ad rows, where a campaign, ad set, ad or launch is in view; it can differ from Meta's own figure for that object by a cent or so, since Meta rounds each ad to cents. notIngested- Metrics not imported on this platform (Meta: none; another platform: the breakdown cards).
period- since, until.
platform- The ad platform, on another platform's answer.
segments- Meta: the segment filters applied, by dimension.
segmentsNote- Meta, with a segment filter by region, product, actionDevice or actionDestination: Meta splits no conversion off its own apps by it, so purchases, their value, carts, checkouts and landing page views are absent, never 0.
settlingFrom- YYYY-MM-DD: from this day on the platform may still change the numbers.
withheld- True where the platform's terms keep its results inside Pluto's own app:
metrics,byCurrency,breakdownanddefinedMetricsare null andwithheldDatasays why. withheldData- Where a platform's terms keep its results inside Pluto's own app: one entry per platform. The results exist and are complete in Pluto; the nulls are not missing data or zero, and asking again, here or elsewhere, gives the same answer. The
Pluto-Withheldheader names the platforms too.
curl "$PLUTO_API/analytics/insights" \
-H "Authorization: Bearer $PLUTO_KEY"Get a launch's results
The same shape as /analytics/insights plus launch; broken down by ad set unless breakdown says otherwise. Without a period: the launch's whole delivery; with nothing delivered yet, period is null and coverage.state says whether an import is running, still to come, or the platform reported no delivery. Coverage is the launch's ad account's.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
launch_id | string | Required | The launch's ID. |
since | string | Optional | First day (YYYY-MM-DD) in each ad account's timezone. |
until | string | Optional | Last day, inclusive. |
attribution | string | Optional | 7d_click_1d_view (the ad set attribution setting, as in Ads Manager), 7d_click, 1d_click, 1d_view or 28d_click. Segment breakdowns and filters read Meta's default, 7d_click_1d_view. |
breakdown | string | Optional | launch, campaign, adSet or ad; or a segment. Meta: age, gender, ageGender, country, region, placement, publisherPlatform, impressionDevice, devicePlatform, hour, actionDevice, actionDestination, actionType, bodyAsset, titleAsset, imageAsset, videoAsset, callToActionAsset, linkUrlAsset, adFormatAsset or product (13 months back). Other platforms with segments: age, gender, country, region, hour, device, network, clickType, slot, conversionAction, searchTerm, keyword, asset, audience or dayOfWeek (from the daily facts). |
age | string | Optional | Only these age ranges (18-24, …, 65+; some platforms also undetermined); repeatable. Segment filters come from one breakdown at a time (on Meta age and gender together are one), and every figure is then the segments' own. |
gender | string | Optional | Meta: female, male or unknown; elsewhere female, male or undetermined; repeatable. |
ageGender | string | Optional | Meta: <age>|<gender>, e.g. 25-34|female; repeatable. |
country | string | Optional | ISO country code; repeatable. |
region | string | Optional | Meta: region as Meta names it; elsewhere the region's geo target ID; repeatable. |
placement | string | Optional | Meta: <platform>|<position>, e.g. instagram|reels; repeatable. |
publisherPlatform | string | Optional | Meta: facebook, instagram, audience_network, messenger or threads; repeatable. |
impressionDevice | string | Optional | Meta: device as Meta names it (iphone, android_smartphone, …); repeatable. |
devicePlatform | string | Optional | Meta: mobile_app, mobile_web or desktop; repeatable. |
hour | string | Optional | hour of the day in the ad account's time zone, 00 to 23; repeatable. |
actionDevice | string | Optional | Meta: the device an action happened on; repeatable. |
actionDestination | string | Optional | Meta: where an action happened; repeatable. |
bodyAsset | string | Optional | Meta: a dynamic or flexible creative's text asset ID; repeatable. |
titleAsset | string | Optional | Meta: headline asset ID; repeatable. |
imageAsset | string | Optional | Meta: image asset ID; repeatable. |
videoAsset | string | Optional | Meta: video asset ID; repeatable. |
callToActionAsset | string | Optional | Meta: call to action asset ID; repeatable. |
linkUrlAsset | string | Optional | Meta: link asset ID; repeatable. |
adFormatAsset | string | Optional | Meta: ad format asset; repeatable. |
format | string | Optional | Meta: the same as adFormatAsset. |
product | string | Optional | Meta: a catalog product as Meta reports product_id; repeatable. |
device | string | Optional | Where the platform reports it: mobile, desktop, tablet, connected_tv or other; repeatable. Other platforms' segment filters come from one breakdown at a time. |
network | string | Optional | Where the platform reports it: search, search_partners, content, youtube_search, youtube_watch, mixed, google_tv or unknown; repeatable. |
clickType | string | Optional | Where the platform reports it: the click type as the platform names it, lower case (url_clicks, call_tracking, sitelinks, …); repeatable. |
slot | string | Optional | Where the platform reports it: search_top, search_other, content, search_partner_top, search_partner_other, mixed or unknown; repeatable. |
conversionAction | string | Optional | Where the platform reports it: a conversion action's ID; only the conversion metrics are split by it; repeatable. |
searchTerm | string | Optional | Where the platform reports it: <search term>|<match type>, e.g. running shoes|broad; repeatable. |
keyword | string | Optional | Where the platform reports it: a keyword's criterion ID; repeatable. |
asset | string | Optional | Where the platform reports it: <asset ID>|<field type>, e.g. 123|headline; repeatable. |
audience | string | Optional | Where the platform reports it: an audience segment's criterion ID; repeatable. |
actionType | string | Optional | Meta: an action type whose action:<type>, action_value:<type> and cost_per_action:<type> every breakdown row carries; repeatable. |
series | string | Optional | An action metric (action:<type>, …) whose series actionMetrics carries; repeatable. |
metric | string | Optional | Only this metric (any ID of the platform's catalogue, action:<type> on Meta), everywhere metrics are, with its definition in definitions; repeatable. An ID the platform doesn't report is a 422 that names the closest IDs it has. |
definitions | string | Optional | true: each metric's definition in definitions (implied by metric). |
sort | string | Optional | With breakdown: order the rows by this metric, descending (-spend too); rows without a value come last. |
order | string | Optional | desc (default) or asc. |
limit | string | Optional | With breakdown: at most this many rows (1 to 1000); breakdown.rowsTotal counts every row in scope. |
cursor | string | Optional | The previous answer's breakdown.nextCursor, the rest of the query unchanged. |
thenBy | string | Optional | With breakdown: split every row again, by day, week or month, or (a breakdown by launch, campaign, ad set or ad) by a segment such as country, age or placement. 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. |
status | string | Optional | Only ads with this status in the platform's words (ACTIVE: delivering now, PAUSED), totals included; repeatable. |
labelId | string | Optional | Only the ads Pluto labelled with this label, totals included; repeatable. |
label | string | Optional | Only the ads Pluto labelled with a label of this name; repeatable. |
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
accountPeriods- With
today, when the ad accounts in view are on different days just now: per group of accounts on one day,accounts(their IDs),sinceanduntil(the days they read forperiod) andcomparisonPeriod(since, until, or null).periodstays as asked; a series point is its day, each account's day counted from the start of its own period (Today: New York's Nov 12 and Copenhagen's Nov 13 are one point), and a series runs longer thanperiodwhere a group's period is (on Dec 1 in Copenhagen, This month is all of New York's November). Reach and frequency stay one account's. Absent when every account readsperiod. actionMetrics- Meta: every action type it counted in the period, custom conversions included, as
action:<type>(the count) and, in one currency,action_value:<type>andcost_per_action:<type>:value,comparisonValue,change;seriesonly for those named inseries. attributionBasisconversionRulewhere each conversion counts in its conversion rule's windows,adGroupSettingwhere in its ad group's own windows.breakdowndimensionandrows(id,name,currency,metrics; an ad row on Meta alsorankings{ quality, engagementRate, conversionRate, asOf } as Meta labels them; a segment row its segment value inidand an asset's or product's text inname, andunattributedfor actions Meta reported without the breakdown's value). Meta:noteby region, product, actionDevice or actionDestination, which Meta splits no conversion off its own apps by (purchases, their value, carts, checkouts, landing page views: absent, never 0);incompleteby actionType andrankingsIncompleteby ad whilecoverage.history.fieldsCompleteFromis after the period's start. A campaign or ad set in Pluto (published from a launch, imported, or kept in sync) also haslaunchId, and an ad set not archived in Pluto itsplutoAdSetId; the ad set performance list's rows the same, withcampaignLaunchIdfor their campaign.byCurrencymetricsandactionMetricsper currency when mixed.byPlatform- With
platforms: each platform's own answer (this shape) by platform, besideplatforms,withheldPlatforms(whose terms keep their results in Pluto),refused(per platform{ message, problems }where it can't answer the question) andnote. Platforms are never added together. changeCoversperiodandcomparisonPeriod(each since, until): the days a change compares while one of the period isn't over yet, so a part of a day is never set against a whole one (the period's days that are over and as many of the comparison period's). Both null: no day of the period is over yet, so no metric has a change. Null when a change covers the whole periods or there's no comparison.comparisonIncomplete- The comparison period reaches back before the history every ad account in view holds (older days still importing; on Meta older than the 37 months it keeps, on another platform older than the days its terms let Pluto keep), or, on Meta with a segment filter or breakdown, outside the days its breakdown set covers (
coverage.breakdowns), so nothing is compared and no metric has a change. comparisonPeriod- since, until, or null.
coveragefrom,to(null without a period),state(importing,notImported,noDelivery,fresh),freshAsOf(least recent import among accounts that have imported; null only when none has),importing,importJobId,nextUpdateAt(when the next pull of the accounts in view is due), per-accountaccounts(freshAsOf,coveredThrough,lastError,importing,history:from(complete back to that day),complete(back to the 37 months Meta keeps),importing(older days still coming),coveredDays,totalDays,limit,nextAt,lastError; thenunreadDays: days Meta couldn't produce even in smaller requests, which keep the numbers they had until a later import reads them),notYetImported,missingAccounts(not imported through the period's end),historyover the accounts in view (from,complete,importing,incompleteAccounts: history not yet back to the period's start;fieldsCompleteFrom, also per account: the first day every field is in while older days are read again with the newer ones, action types, video plays, watch time and rankings) and, on Meta when breakdowns were read,breakdownsper breakdown set (from,through: the last day read to its end,readAt,complete: back to the 13 months Meta keeps,level:accountfor whole ad accounts oradfor a read narrowed to a campaign, ad set, ad or launch, whose segments cover the last 14 days,unreadDays: days Meta couldn't produce, which keep the numbers they had,unavailableAccounts:id,name,reason, ad accounts Meta refused it for, such as impression device before it's enabled on the account).currencies- Currencies in view. More than one: amounts are per currency in
byCurrencyand never added together. currency- ISO 4217; null when rows span several currencies.
dayBasisutcwhere the platform reports UTC days,accountwhere it reports the ad account's time zone days, on another platform's answer.definitions- With
definitions=trueormetric: per metric ID{ id, name, unit, aggregation, summable, perCurrency, lowerIsBetter }.unitis money, count, fraction, multiple or seconds;aggregationis sum, ratio (recomputed from the sums), weighted (by impressions) or window (the platform's own figure for exactly the period and object, like reach, frequency and unique clicks: never summed, so breakdown rows don't add up to it). freshness- How late the platform's numbers usually arrive, where it says:
metricsMinutes,reachMinutes. inProgressFrom- YYYY-MM-DD: the period's first day that isn't over yet in the time zone of every ad account in view (null when the period is over). From it on a series point holds only part of its days so far, or none yet.
intervalday,weekormonth: what one series point covers; a point'skeyis its first day in the period.metrics- Per metric:
value(decimal string; money in the account currency, ratios as fractions),series,comparisonValueandchange{ absolute, relative }against the comparison period. Ratios are recomputed per period from that period's sums, never averaged;relativeis a fraction and absent when the previous value is 0;changeis absent when either period has no value. While a day of the period isn't over yet (changeCovers),changecovers the days that are over and also carries the two values it is taken between,valueandcomparisonValueover those days; the metric's ownvalueandcomparisonValuestay the whole periods'. Metrics Meta reported nothing for are absent, never 0.incomplete: trueon Meta: the metric reads fields the ad accounts' older days are still being read again with (action types, video plays, watch time, engagement), and the period reaches beforecoverage.history.fieldsCompleteFrom. moneyBasis- Meta's answer: where its money comes from.
account: Meta's own figure for each ad account and day, in the attribution setting read, as Ads Manager shows it.ads: the sum of the ad rows, where a campaign, ad set, ad or launch is in view; it can differ from Meta's own figure for that object by a cent or so, since Meta rounds each ad to cents. notIngested- Metrics not imported on this platform (Meta: none; another platform: the breakdown cards).
period- since, until.
platform- The ad platform, on another platform's answer.
segments- Meta: the segment filters applied, by dimension.
segmentsNote- Meta, with a segment filter by region, product, actionDevice or actionDestination: Meta splits no conversion off its own apps by it, so purchases, their value, carts, checkouts and landing page views are absent, never 0.
settlingFrom- YYYY-MM-DD: from this day on the platform may still change the numbers.
withheld- True where the platform's terms keep its results inside Pluto's own app:
metrics,byCurrency,breakdownanddefinedMetricsare null andwithheldDatasays why. withheldData- Where a platform's terms keep its results inside Pluto's own app: one entry per platform. The results exist and are complete in Pluto; the nulls are not missing data or zero, and asking again, here or elsewhere, gives the same answer. The
Pluto-Withheldheader names the platforms too.
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/analytics/launches/2046ac37-4775-4757-9ef2-3d948cbfc560" \
-H "Authorization: Bearer $PLUTO_KEY"Rank ads by metric
Ranks one platform's ads by a metric on the server, over every ad in scope (platform; default: the platform of the ad accounts, campaigns, ad sets, ads or launches named, else the last-used connected platform), within each currency: the top or bottom ads by any per-ad metric that platform reports, for a named period or since and until, filtered by ad account, campaign, ad set, ad, launch, segment, status, minimum spend or minimum purchases. Each ad comes with its name, status, campaign and ad set, its launch and Pluto link when a launch manages it, its metrics and what Creative Memory found in its files; a Meta ad also its Ads Manager link, thumbnail, Page and Meta's rankings, another platform's ad its ID there, its delivery and managerUrl. The same answer as the MCP tool rank_ads for the same arguments. Lists repeat their key (campaignId=A&campaignId=B), a segment filter is the segment's name (country=US&country=CA), every other parameter comes once; an unknown parameter is a 422. A credential limited to some ad accounts ranks only theirs. Where a platform's terms keep its results inside Pluto's own app, nothing is ranked (rankings is empty, withheld is true) and withheldData and the Pluto-Withheld header say why.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Optional | A platform from GET /platforms (default: the platform of the ad accounts, campaigns, ad sets, ads or launches named, else the last-used connected platform). Each ranks by its own metrics: one it doesn't report is a 422. |
period | string | Optional | A named period counted from today as the app's date picker counts it (default last_30_days): today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days (today included), this_month (so far), last_month, each read in every ad account's own days from its own today; or all_time (everything the platform keeps). Or give since and until instead. |
since | string | Optional | First day (YYYY-MM-DD), instead of period. |
until | string | Optional | Last day, inclusive, with since. |
metric | string | Optional | What to rank by (default spend): a per-ad metric ID the platform reports (GET /analytics/insights with definitions=true lists them); on Meta also action:<type>, action_value:<type> or cost_per_action:<type>, custom conversions included. |
order | string | Optional | desc (highest first) or asc. Default: best first, asc for costs such as cpa, cpc and cpm, desc otherwise. |
limit | string | Optional | Ads per ranking, 1 to 50 (default 10). |
offset | string | Optional | Skip this many ranked ads: the previous page's nextOffset. |
minSpend | string | Optional | Only ads that spent at least this much in the period (decimal, account currency). Set it for ROAS or cost rankings so ads with a single result don't lead. |
minPurchases | string | Optional | Only ads with at least this many purchases in the period; a platform without purchases answers 422. |
status | string | Optional | Only ads with this status on their platform, e.g. ACTIVE (running now) or PAUSED; elsewhere also its delivery (UNDER_REVIEW, REJECTED, …). |
attribution | string | Optional | Meta's attribution setting: 7d_click_1d_view (default), 7d_click, 1d_click, 1d_view or 28d_click. Another platform takes none. |
currency | string | Optional | Only accounts billing in this ISO 4217 currency. |
creative | string | Optional | false leaves out what Creative Memory found in each ad's files (default true). |
posts | string | Optional | true: each Meta ad's Facebook and Instagram post links, read from Meta (the first 25 ads). |
metrics | string | Optional | The metrics each ad carries, by metric ID; repeatable; all for every one. Default: the ranked metric with the platform's usual figures (on Meta spend, purchase_value, roas, purchases, cpa, results, cost_per_result, impressions, clicks and ctr; elsewhere spend, leads, cost_per_lead, conversions, cost_per_conversion, roas, impressions, clicks, link_clicks, ctr and cpc, each where the platform reports it). |
adAccountId | string | Optional | Repeatable. |
campaignId | string | Optional | Repeatable. |
adSetId | string | Optional | Repeatable. |
adId | string | Optional | Repeatable. |
launchId | string | Optional | Only ads these launches published; repeatable. |
age | string | Optional | Only these age ranges (18-24, …, 65+; some platforms also undetermined); repeatable. Segment filters come from one breakdown at a time (on Meta age and gender together are one), and every figure is then the segments' own. |
gender | string | Optional | Meta: female, male or unknown; elsewhere female, male or undetermined; repeatable. |
ageGender | string | Optional | Meta: <age>|<gender>, e.g. 25-34|female; repeatable. |
country | string | Optional | ISO country code; repeatable. |
region | string | Optional | Meta: region as Meta names it; elsewhere the region's geo target ID; repeatable. |
placement | string | Optional | Meta: <platform>|<position>, e.g. instagram|reels; repeatable. |
publisherPlatform | string | Optional | Meta: facebook, instagram, audience_network, messenger or threads; repeatable. |
impressionDevice | string | Optional | Meta: device as Meta names it (iphone, android_smartphone, …); repeatable. |
devicePlatform | string | Optional | Meta: mobile_app, mobile_web or desktop; repeatable. |
hour | string | Optional | hour of the day in the ad account's time zone, 00 to 23; repeatable. |
actionDevice | string | Optional | Meta: the device an action happened on; repeatable. |
actionDestination | string | Optional | Meta: where an action happened; repeatable. |
bodyAsset | string | Optional | Meta: a dynamic or flexible creative's text asset ID; repeatable. |
titleAsset | string | Optional | Meta: headline asset ID; repeatable. |
imageAsset | string | Optional | Meta: image asset ID; repeatable. |
videoAsset | string | Optional | Meta: video asset ID; repeatable. |
callToActionAsset | string | Optional | Meta: call to action asset ID; repeatable. |
linkUrlAsset | string | Optional | Meta: link asset ID; repeatable. |
adFormatAsset | string | Optional | Meta: ad format asset; repeatable. |
product | string | Optional | Meta: a catalog product as Meta reports product_id; repeatable. |
device | string | Optional | Where the platform reports it: mobile, desktop, tablet, connected_tv or other; repeatable. Other platforms' segment filters come from one breakdown at a time. |
network | string | Optional | Where the platform reports it: search, search_partners, content, youtube_search, youtube_watch, mixed, google_tv or unknown; repeatable. |
clickType | string | Optional | Where the platform reports it: the click type as the platform names it, lower case (url_clicks, call_tracking, sitelinks, …); repeatable. |
slot | string | Optional | Where the platform reports it: search_top, search_other, content, search_partner_top, search_partner_other, mixed or unknown; repeatable. |
conversionAction | string | Optional | Where the platform reports it: a conversion action's ID; only the conversion metrics are split by it; repeatable. |
searchTerm | string | Optional | Where the platform reports it: <search term>|<match type>, e.g. running shoes|broad; repeatable. |
keyword | string | Optional | Where the platform reports it: a keyword's criterion ID; repeatable. |
asset | string | Optional | Where the platform reports it: <asset ID>|<field type>, e.g. 123|headline; repeatable. |
audience | string | Optional | Where the platform reports it: an audience segment's criterion ID; repeatable. |
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
attribution- The attribution setting (Meta's; null elsewhere).
coverage- As /analytics/insights: how current the numbers are.
metric- What the ads are ranked by.
note- Where the numbers show, when they're withheld.
orderdesc: highest first.One ofdesc,ascperiodsince,until: the days ranked.platform- The ad platform ranked.
postsUnavailable- Why the post links couldn't be read, when
posts=trueasked for them and they couldn't be (another platform's ads have none here). rankings- A ranking per currency in scope; money never adds up across currencies.
withheld- True where the platform's terms keep its results inside Pluto's own app: nothing is ranked (
rankingsis empty),notesays where they show andwithheldDatawhy. withheldData- Where a platform's terms keep its results inside Pluto's own app: one entry per platform. Asking again, here or elsewhere, gives the same answer. The
Pluto-Withheldheader names the platforms too.
curl "$PLUTO_API/analytics/rankings" \
-H "Authorization: Bearer $PLUTO_KEY"Import insights now
A command (send Idempotency-Key; a retry replays the first answer). Queues an insights import of one platform's ad accounts (platform; default: the ad accounts' platform, else the last-used connected platform): those in adAccountIds, or every synced one without it. Follow it at /jobs/{id}. On Meta it returns the import already queued or running that covers them (queued: false) and starts at most 2 new imports per workspace per 15 minutes (429 with Retry-After beyond), inside Meta's ads_insights rate limit. 409 when the platform isn't connected or has no ad accounts on; 422 when adAccountIds names an ad account the connection doesn't have.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
adAccountIds- Only these ad accounts. Every synced ad account when absent.
platform- A platform from
GET /platforms(default: the ad accounts' platform, else the last-used connected platform).
Response
jobId- The insights import job.
queued- false when an open import was returned.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/analytics/refresh" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: f27b18de-9be0-4277-ab0e-3bb4aec3ecf9" \
-H "Content-Type: application/json" \
-d '{
"adAccountIds": [
"act_741877585619437"
],
"platform": "Brevanne"
}'Get a platform's reports
The reports of a platform that has reports of its own beyond the shared insights (GET /platforms says which platforms a workspace has; one without such reports answers 422 on platform, one without a level answers 422 on level), in that platform's own columns and names, from the insights Pluto imported: one row per ad account, campaign, ad, keyword, search term or bid strategy over the period, highest cost first, and where the platform has them its budget summary, call detail, goals and funnels, share of voice and quality score reports (those it keeps per day are a row per day, never summed). Where the platform's reports take time, daily, weekly (Sunday to Saturday) or monthly sums each period of the reports that add up, the period widened to whole weeks or months as the platform does. The columns the platform asks to be shown by default are marked default; the others are there to add. Money is decimal text in each row's currency and is never added across ad accounts. A JSON answer is a page of rows in a fixed order: pass its nextCursor as cursor (with the same query) for the next page, until nextCursor is null. format=csv downloads every row with every column.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Optional | A platform from GET /platforms. |
level | string | Optional | account, campaign, ad, keyword, search_term or bidding_strategy; where the platform has them, budget_summary, call_detail, goals_and_funnels, share_of_voice and quality_score. |
time | string | Optional | summary (default), daily, weekly or monthly, where the platform's reports take it (others answer 422 on time). |
since | string | Optional | First day (YYYY-MM-DD), in each ad account's time zone. |
until | string | Optional | Last day (YYYY-MM-DD). |
adAccountId | string | Optional | Only these ad accounts; repeatable or comma-separated. |
format | string | Optional | json (default) or csv. |
limit | string | Optional | Rows in a page of a JSON answer (1-10000, default 1000). |
cursor | string | Optional | The nextCursor of the page before, for the next page. |
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
columns- The report's columns, in order.
columns[].default- Whether the platform asks for the column to be shown without being asked for.
columns[].id- The column's key in every row.
columns[].kindtext,number,money(decimal text in the row'scurrency) orstatus.columns[].name- The column's name as the platform's own reports call it.
dayBasisaccount: days are each ad account's own time zone days.levelaccount,campaign,ad,keyword,search_termorbidding_strategy; where the platform has them,budget_summary,call_detail,goals_and_funnels,share_of_voiceandquality_score.nextCursor- The next page's
cursor; null on the last page. periodperiod.since- First day.
period.until- Last day.
platform- The platform the report is of.
rows- Highest cost first; per day, week or month the newest first.
time- Where the platform's reports take it: how the days came together,
summary,daily,weeklyormonthly. truncated- More rows follow this page (
nextCursor).
curl "$PLUTO_API/analytics/reports" \
-H "Authorization: Bearer $PLUTO_KEY"Get numbers by segment
One campaign's numbers for a period split by who or where they reached (by: age, gender, platforms, regions or metros) or by the conversion event that counted them (conversion_tags), read from the platform when asked and never stored, on a platform that reports segments this way (422 on one that doesn't), on one of the platform's placements (placement). The platform prepares the answer as a job: the request waits a short while for it, then answers the rows, or 202 with pending: true and a jobId to pass back on the same request. A period is 45 days at most. by=placement splits the ad account's numbers (or one campaign's) by where they ran, from what Pluto already read, at once and for any period it holds. Where the platform's terms keep its data inside Pluto's own app, rows is null and withheld is true on every other channel, and the platform isn't asked.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Optional | A platform from GET /platforms. |
by | string | Optional | age, gender, platforms, regions, metros, conversion_tags or placement. |
campaignId | string | Optional | The campaign, by its ID at the platform; optional for placement. |
adAccountId | string | Optional | The ad account; optional when one is connected. |
since | string | Optional | First day (YYYY-MM-DD, the ad account's days). |
until | string | Optional | Last day (YYYY-MM-DD). |
country | string | Optional | The platform's value for the country; needed for regions and metros. |
placement | string | Optional | The placement a split is read on: ALL_ON_TWITTER (the default) or PUBLISHER_NETWORK. |
jobId | string | Optional | The job of an answer that was pending. |
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
by- The segmentation asked.
currency- The ad account's currency (ISO 4217).
jobId- The platform's job for this answer. Pass it back while
pending. note- Where the numbers show, when they're withheld.
pendingtruewhile the platform still prepares the answer: ask again withjobId.period- since, until.
platform- The platform asked.
rows- One row per segment:
name(the platform's name for it) andmetrics(the platform's own metric names, decimal strings;spendin the account's currency). Null while pending, and wherewithheld. withheld- The platform's terms keep what is read from it inside Pluto's own app:
rowsis left out here.
curl "$PLUTO_API/analytics/segments" \
-H "Authorization: Bearer $PLUTO_KEY"