API reference

Analytics

Ad performance from Meta and LinkedIn and X, and the dashboard layout.

GET/analytics/auction-insights

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformquerystringOptionalA platform from GET /platforms.
sincequerystringOptionalFirst day (YYYY-MM-DD), in the ad account's time zone, within the days the platform keeps (retentionDays).
untilquerystringOptionalLast day (YYYY-MM-DD).
adAccountIdquerystringOptionalThe ad account; the first one reachable when left out.
levelquerystringOptionalaccount (default), campaign, ad_group or keyword.
idquerystringOptionalA campaign, ad group or keyword ID from entities (up to 200, repeatable or comma-separated); none at account.
segmentquerystringOptionalday, week, month, quarter, day_of_week or device (up to three, repeatable).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accountsarray of objectsRequired
The ad accounts to choose from.
accounts[].idstringRequired
The platform's ID.
accounts[].namestring or null
Its name; null where the platform's terms keep it in Pluto's own app.
adAccountIdstring or null
The ad account the insights are of (the first one reachable when none was named); null with none.
entitiesarray of objectsRequired
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/entities from entitiesNext.
entitiesNextstring or null
The cursor of entities' next page; null when it holds them all.
entitiesTruncatedboolean
More follow entities' first page (entitiesNext).
entriesarray of objectsRequired
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[].absoluteTopOfPageRatestring or null
Absolute top of page rate (0 to 1).
entries[].displayDomainstringRequired
The advertiser's display domain, as the platform wrote it.
entries[].impressionSharestring or null
Impression share: a share from 0 to 1, as decimal text.
entries[].outrankingSharestring or null
Outranking share: how often your ad ranked above its, or showed when its didn't (0 to 1).
entries[].overlapRatestring or null
Overlap rate: how often this domain's ad showed when yours did (0 to 1).
entries[].positionAboveRatestring or null
Position above rate: how often its ad showed above yours (0 to 1).
entries[].segmentedarray of objectsRequired
The same rates per combination of the segments asked; empty without segments.
entries[].segmented[].absoluteTopOfPageRatestring or null
Absolute top of page rate (0 to 1).
entries[].segmented[].impressionSharestring or null
Impression share: a share from 0 to 1, as decimal text.
entries[].segmented[].outrankingSharestring or null
Outranking share: how often your ad ranked above its, or showed when its didn't (0 to 1).
entries[].segmented[].overlapRatestring or null
Overlap rate: how often this domain's ad showed when yours did (0 to 1).
entries[].segmented[].positionAboveRatestring or null
Position above rate: how often its ad showed above yours (0 to 1).
entries[].segmented[].segmentsarray of stringsRequired
One value per segment, in segments' order.
entries[].segmented[].topOfPageRatestring or null
Top of page rate (0 to 1).
entries[].topOfPageRatestring or null
Top of page rate (0 to 1).
idsarray of stringsRequired
The campaigns, ad groups or keywords asked about.
levelstringRequired
account, campaign, ad_group or keyword.
periodobjectRequired
period.sincestringRequired
First day.
period.untilstringRequired
Last day.
platformstringRequired
The platform the insights are of.
retentionDaysinteger
How many days back the platform keeps auction insights.
segmentsarray of stringsRequired
How each segmented row is split, in order.
sourcestring
Who answered: the numbers are the platform's own.
usedImpressionsstring or null
The share of impressions the entries were made from (0 to 1), as decimal text.
usedKeywordsstring or null
How many keywords the entries were made from.
withheldboolean
The platform's terms keep these numbers in Pluto's own app: they exist there, and asking again here gives the same answer.

Errors

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

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformquerystringOptionalA platform from GET /platforms that offers auction insights.
adAccountIdquerystringOptionalThe ad account; the first one reachable when left out.
levelquerystringOptionalcampaign (default), ad_group or keyword.
searchquerystringOptionalWords that every result's names hold, in any order.
cursorquerystringOptionalThe nextCursor of the page before.
limitquerystringOptionalEntities in a page (1-200, default 200).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adAccountIdstring or null
The ad account; null with none.
entitiesarray of objectsRequired
This page, by name.
levelstringRequired
campaign, ad_group or keyword.
nextCursorstring or nullRequired
The next page's cursor; null on the last page.
platformstringRequired
The platform.

Errors

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

Get the dashboard layout

Permission: read

Parameters

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

Response200 OK

sections, isDefault, version and defaultSections (what a reset restores).

Errors

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

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersionintegerRequired
The version you last read. A mismatch is a conflict that returns the current entity.
sectionsarray of objectsRequired
Layout.

Response200 OK

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PUT "$PLUTO_API/analytics/dashboard" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 5d8150fe-d6a3-47b3-80a6-28e6d21a1fb9" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedVersion": 3,
    "sections": [
      {}
    ]
  }'
DELETE/analytics/dashboard

Restore the default layout

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

expectedVersioninteger
Optional: the version you last read. A layout saved since then is a 409 with the current layout instead of being dropped.

Response200 OK

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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X 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/analytics/insights

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.

Permission: read

Parameters

NameTypeRequiredDescription
sincequerystringOptionalFirst day (YYYY-MM-DD) in each ad account's timezone.
untilquerystringOptionalLast day, inclusive.
attributionquerystringOptional7d_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.
breakdownquerystringOptionallaunch, 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).
agequerystringOptionalOnly 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.
genderquerystringOptionalMeta: female, male or unknown; elsewhere female, male or undetermined; repeatable.
ageGenderquerystringOptionalMeta: <age>|<gender>, e.g. 25-34|female; repeatable.
countryquerystringOptionalISO country code; repeatable.
regionquerystringOptionalMeta: region as Meta names it; elsewhere the region's geo target ID; repeatable.
placementquerystringOptionalMeta: <platform>|<position>, e.g. instagram|reels; repeatable.
publisherPlatformquerystringOptionalMeta: facebook, instagram, audience_network, messenger or threads; repeatable.
impressionDevicequerystringOptionalMeta: device as Meta names it (iphone, android_smartphone, …); repeatable.
devicePlatformquerystringOptionalMeta: mobile_app, mobile_web or desktop; repeatable.
hourquerystringOptionalhour of the day in the ad account's time zone, 00 to 23; repeatable.
actionDevicequerystringOptionalMeta: the device an action happened on; repeatable.
actionDestinationquerystringOptionalMeta: where an action happened; repeatable.
bodyAssetquerystringOptionalMeta: a dynamic or flexible creative's text asset ID; repeatable.
titleAssetquerystringOptionalMeta: headline asset ID; repeatable.
imageAssetquerystringOptionalMeta: image asset ID; repeatable.
videoAssetquerystringOptionalMeta: video asset ID; repeatable.
callToActionAssetquerystringOptionalMeta: call to action asset ID; repeatable.
linkUrlAssetquerystringOptionalMeta: link asset ID; repeatable.
adFormatAssetquerystringOptionalMeta: ad format asset; repeatable.
formatquerystringOptionalMeta: the same as adFormatAsset.
productquerystringOptionalMeta: a catalog product as Meta reports product_id; repeatable.
devicequerystringOptionalWhere the platform reports it: mobile, desktop, tablet, connected_tv or other; repeatable. Other platforms' segment filters come from one breakdown at a time.
networkquerystringOptionalWhere the platform reports it: search, search_partners, content, youtube_search, youtube_watch, mixed, google_tv or unknown; repeatable.
clickTypequerystringOptionalWhere the platform reports it: the click type as the platform names it, lower case (url_clicks, call_tracking, sitelinks, …); repeatable.
slotquerystringOptionalWhere the platform reports it: search_top, search_other, content, search_partner_top, search_partner_other, mixed or unknown; repeatable.
conversionActionquerystringOptionalWhere the platform reports it: a conversion action's ID; only the conversion metrics are split by it; repeatable.
searchTermquerystringOptionalWhere the platform reports it: <search term>|<match type>, e.g. running shoes|broad; repeatable.
keywordquerystringOptionalWhere the platform reports it: a keyword's criterion ID; repeatable.
assetquerystringOptionalWhere the platform reports it: <asset ID>|<field type>, e.g. 123|headline; repeatable.
audiencequerystringOptionalWhere the platform reports it: an audience segment's criterion ID; repeatable.
actionTypequerystringOptionalMeta: an action type whose action:<type>, action_value:<type> and cost_per_action:<type> every breakdown row carries; repeatable.
seriesquerystringOptionalAn action metric (action:<type>, …) whose series actionMetrics carries; repeatable.
platformquerystringOptionalA platform from GET /platforms (default meta). Its ad account, campaign, ad set and ad IDs go in the ID filters.
compare_sincequerystringOptionalComparison period start.
compare_untilquerystringOptionalComparison period end.
todayquerystringOptionalThis 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.
presetquerystringOptionalWith 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.
comparisonquerystringOptionalWith 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.
intervalquerystringOptionalday (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.
adAccountIdquerystringOptionalRepeatable.
accountquerystringOptionalAd account name; repeatable.
campaignIdquerystringOptionalRepeatable.
campaignquerystringOptionalCampaign name; repeatable.
adSetIdquerystringOptionalRepeatable.
adSetquerystringOptionalAd set name; repeatable.
adIdquerystringOptionalRepeatable.
launchIdquerystringOptionalRepeatable.
launchquerystringOptionalLaunch name; repeatable.
currencyquerystringOptionalOnly accounts in this ISO 4217 currency.
platformsquerystringOptionalSeveral 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.
metricquerystringOptionalOnly 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.
definitionsquerystringOptionaltrue: each metric's definition in definitions (implied by metric).
sortquerystringOptionalWith breakdown: order the rows by this metric, descending (-spend too); rows without a value come last.
orderquerystringOptionaldesc (default) or asc.
limitquerystringOptionalWith breakdown: at most this many rows (1 to 1000); breakdown.rowsTotal counts every row in scope.
cursorquerystringOptionalThe previous answer's breakdown.nextCursor, the rest of the query unchanged.
thenByquerystringOptionalWith 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.
statusquerystringOptionalOnly ads with this status in the platform's words (ACTIVE: delivering now, PAUSED), totals included; repeatable.
labelIdquerystringOptionalOnly the ads Pluto labelled with this label, totals included; repeatable.
labelquerystringOptionalOnly the ads Pluto labelled with a label of this name; repeatable.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accountPeriodsarray of objects
With today, when the ad accounts in view are on different days just now: per group of accounts on one day, accounts (their IDs), since and until (the days they read for period) and comparisonPeriod (since, until, or null). period stays 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 than period where 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 reads period.
actionMetricsobject
Meta: every action type it counted in the period, custom conversions included, as action:<type> (the count) and, in one currency, action_value:<type> and cost_per_action:<type>: value, comparisonValue, change; series only for those named in series.
attributionBasisstring
conversionRule where each conversion counts in its conversion rule's windows, adGroupSetting where in its ad group's own windows.
breakdownobject
dimension and rows (id, name, currency, metrics; an ad row on Meta also rankings { quality, engagementRate, conversionRate, asOf } as Meta labels them; a segment row its segment value in id and an asset's or product's text in name, and unattributed for actions Meta reported without the breakdown's value). Meta: note by 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); incomplete by actionType and rankingsIncomplete by ad while coverage.history.fieldsCompleteFrom is after the period's start. A campaign or ad set in Pluto (published from a launch, imported, or kept in sync) also has launchId, and an ad set not archived in Pluto its plutoAdSetId; the ad set performance list's rows the same, with campaignLaunchId for their campaign.
byCurrencyobject
metrics and actionMetrics per currency when mixed.
byPlatformobject
With platforms: each platform's own answer (this shape) by platform, beside platforms, withheldPlatforms (whose terms keep their results in Pluto), refused (per platform { message, problems } where it can't answer the question) and note. Platforms are never added together.
changeCoversobject or null
period and comparisonPeriod (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.
comparisonIncompleteboolean
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.
comparisonPeriodobject
since, until, or null.
coverageobject
from, 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-account accounts (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; then unreadDays: 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), history over 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, breakdowns per breakdown set (from, through: the last day read to its end, readAt, complete: back to the 13 months Meta keeps, level: account for whole ad accounts or ad for 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).
currenciesarray of strings
Currencies in view. More than one: amounts are per currency in byCurrency and never added together.
currencystring or null
ISO 4217; null when rows span several currencies.
dayBasisstring
utc where the platform reports UTC days, account where it reports the ad account's time zone days, on another platform's answer.
definitionsobject
With definitions=true or metric: per metric ID { id, name, unit, aggregation, summable, perCurrency, lowerIsBetter }. unit is money, count, fraction, multiple or seconds; aggregation is 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).
freshnessobject
How late the platform's numbers usually arrive, where it says: metricsMinutes, reachMinutes.
inProgressFromstring or null
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.
intervalstring
day, week or month: what one series point covers; a point's key is its first day in the period.
metricsobject
Per metric: value (decimal string; money in the account currency, ratios as fractions), series, comparisonValue and change { absolute, relative } against the comparison period. Ratios are recomputed per period from that period's sums, never averaged; relative is a fraction and absent when the previous value is 0; change is absent when either period has no value. While a day of the period isn't over yet (changeCovers), change covers the days that are over and also carries the two values it is taken between, value and comparisonValue over those days; the metric's own value and comparisonValue stay the whole periods'. Metrics Meta reported nothing for are absent, never 0. incomplete: true on 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 before coverage.history.fieldsCompleteFrom.
moneyBasisstring
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.
notIngestedarray of strings
Metrics not imported on this platform (Meta: none; another platform: the breakdown cards).
periodobjectRequired
since, until.
platformstring
The ad platform, on another platform's answer.
segmentsobject
Meta: the segment filters applied, by dimension.
segmentsNotestring or null
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.
settlingFromstring
YYYY-MM-DD: from this day on the platform may still change the numbers.
withheldboolean
True where the platform's terms keep its results inside Pluto's own app: metrics, byCurrency, breakdown and definedMetrics are null and withheldData says why.
withheldDataarray of objects
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-Withheld header names the platforms too.

Errors

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

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.

Permission: read

Parameters

NameTypeRequiredDescription
launch_idpathstringRequiredThe launch's ID.
sincequerystringOptionalFirst day (YYYY-MM-DD) in each ad account's timezone.
untilquerystringOptionalLast day, inclusive.
attributionquerystringOptional7d_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.
breakdownquerystringOptionallaunch, 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).
agequerystringOptionalOnly 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.
genderquerystringOptionalMeta: female, male or unknown; elsewhere female, male or undetermined; repeatable.
ageGenderquerystringOptionalMeta: <age>|<gender>, e.g. 25-34|female; repeatable.
countryquerystringOptionalISO country code; repeatable.
regionquerystringOptionalMeta: region as Meta names it; elsewhere the region's geo target ID; repeatable.
placementquerystringOptionalMeta: <platform>|<position>, e.g. instagram|reels; repeatable.
publisherPlatformquerystringOptionalMeta: facebook, instagram, audience_network, messenger or threads; repeatable.
impressionDevicequerystringOptionalMeta: device as Meta names it (iphone, android_smartphone, …); repeatable.
devicePlatformquerystringOptionalMeta: mobile_app, mobile_web or desktop; repeatable.
hourquerystringOptionalhour of the day in the ad account's time zone, 00 to 23; repeatable.
actionDevicequerystringOptionalMeta: the device an action happened on; repeatable.
actionDestinationquerystringOptionalMeta: where an action happened; repeatable.
bodyAssetquerystringOptionalMeta: a dynamic or flexible creative's text asset ID; repeatable.
titleAssetquerystringOptionalMeta: headline asset ID; repeatable.
imageAssetquerystringOptionalMeta: image asset ID; repeatable.
videoAssetquerystringOptionalMeta: video asset ID; repeatable.
callToActionAssetquerystringOptionalMeta: call to action asset ID; repeatable.
linkUrlAssetquerystringOptionalMeta: link asset ID; repeatable.
adFormatAssetquerystringOptionalMeta: ad format asset; repeatable.
formatquerystringOptionalMeta: the same as adFormatAsset.
productquerystringOptionalMeta: a catalog product as Meta reports product_id; repeatable.
devicequerystringOptionalWhere the platform reports it: mobile, desktop, tablet, connected_tv or other; repeatable. Other platforms' segment filters come from one breakdown at a time.
networkquerystringOptionalWhere the platform reports it: search, search_partners, content, youtube_search, youtube_watch, mixed, google_tv or unknown; repeatable.
clickTypequerystringOptionalWhere the platform reports it: the click type as the platform names it, lower case (url_clicks, call_tracking, sitelinks, …); repeatable.
slotquerystringOptionalWhere the platform reports it: search_top, search_other, content, search_partner_top, search_partner_other, mixed or unknown; repeatable.
conversionActionquerystringOptionalWhere the platform reports it: a conversion action's ID; only the conversion metrics are split by it; repeatable.
searchTermquerystringOptionalWhere the platform reports it: <search term>|<match type>, e.g. running shoes|broad; repeatable.
keywordquerystringOptionalWhere the platform reports it: a keyword's criterion ID; repeatable.
assetquerystringOptionalWhere the platform reports it: <asset ID>|<field type>, e.g. 123|headline; repeatable.
audiencequerystringOptionalWhere the platform reports it: an audience segment's criterion ID; repeatable.
actionTypequerystringOptionalMeta: an action type whose action:<type>, action_value:<type> and cost_per_action:<type> every breakdown row carries; repeatable.
seriesquerystringOptionalAn action metric (action:<type>, …) whose series actionMetrics carries; repeatable.
metricquerystringOptionalOnly 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.
definitionsquerystringOptionaltrue: each metric's definition in definitions (implied by metric).
sortquerystringOptionalWith breakdown: order the rows by this metric, descending (-spend too); rows without a value come last.
orderquerystringOptionaldesc (default) or asc.
limitquerystringOptionalWith breakdown: at most this many rows (1 to 1000); breakdown.rowsTotal counts every row in scope.
cursorquerystringOptionalThe previous answer's breakdown.nextCursor, the rest of the query unchanged.
thenByquerystringOptionalWith 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.
statusquerystringOptionalOnly ads with this status in the platform's words (ACTIVE: delivering now, PAUSED), totals included; repeatable.
labelIdquerystringOptionalOnly the ads Pluto labelled with this label, totals included; repeatable.
labelquerystringOptionalOnly the ads Pluto labelled with a label of this name; repeatable.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accountPeriodsarray of objects
With today, when the ad accounts in view are on different days just now: per group of accounts on one day, accounts (their IDs), since and until (the days they read for period) and comparisonPeriod (since, until, or null). period stays 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 than period where 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 reads period.
actionMetricsobject
Meta: every action type it counted in the period, custom conversions included, as action:<type> (the count) and, in one currency, action_value:<type> and cost_per_action:<type>: value, comparisonValue, change; series only for those named in series.
attributionBasisstring
conversionRule where each conversion counts in its conversion rule's windows, adGroupSetting where in its ad group's own windows.
breakdownobject
dimension and rows (id, name, currency, metrics; an ad row on Meta also rankings { quality, engagementRate, conversionRate, asOf } as Meta labels them; a segment row its segment value in id and an asset's or product's text in name, and unattributed for actions Meta reported without the breakdown's value). Meta: note by 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); incomplete by actionType and rankingsIncomplete by ad while coverage.history.fieldsCompleteFrom is after the period's start. A campaign or ad set in Pluto (published from a launch, imported, or kept in sync) also has launchId, and an ad set not archived in Pluto its plutoAdSetId; the ad set performance list's rows the same, with campaignLaunchId for their campaign.
byCurrencyobject
metrics and actionMetrics per currency when mixed.
byPlatformobject
With platforms: each platform's own answer (this shape) by platform, beside platforms, withheldPlatforms (whose terms keep their results in Pluto), refused (per platform { message, problems } where it can't answer the question) and note. Platforms are never added together.
changeCoversobject or null
period and comparisonPeriod (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.
comparisonIncompleteboolean
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.
comparisonPeriodobject
since, until, or null.
coverageobject
from, 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-account accounts (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; then unreadDays: 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), history over 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, breakdowns per breakdown set (from, through: the last day read to its end, readAt, complete: back to the 13 months Meta keeps, level: account for whole ad accounts or ad for 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).
currenciesarray of strings
Currencies in view. More than one: amounts are per currency in byCurrency and never added together.
currencystring or null
ISO 4217; null when rows span several currencies.
dayBasisstring
utc where the platform reports UTC days, account where it reports the ad account's time zone days, on another platform's answer.
definitionsobject
With definitions=true or metric: per metric ID { id, name, unit, aggregation, summable, perCurrency, lowerIsBetter }. unit is money, count, fraction, multiple or seconds; aggregation is 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).
freshnessobject
How late the platform's numbers usually arrive, where it says: metricsMinutes, reachMinutes.
inProgressFromstring or null
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.
intervalstring
day, week or month: what one series point covers; a point's key is its first day in the period.
metricsobject
Per metric: value (decimal string; money in the account currency, ratios as fractions), series, comparisonValue and change { absolute, relative } against the comparison period. Ratios are recomputed per period from that period's sums, never averaged; relative is a fraction and absent when the previous value is 0; change is absent when either period has no value. While a day of the period isn't over yet (changeCovers), change covers the days that are over and also carries the two values it is taken between, value and comparisonValue over those days; the metric's own value and comparisonValue stay the whole periods'. Metrics Meta reported nothing for are absent, never 0. incomplete: true on 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 before coverage.history.fieldsCompleteFrom.
moneyBasisstring
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.
notIngestedarray of strings
Metrics not imported on this platform (Meta: none; another platform: the breakdown cards).
periodobjectRequired
since, until.
platformstring
The ad platform, on another platform's answer.
segmentsobject
Meta: the segment filters applied, by dimension.
segmentsNotestring or null
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.
settlingFromstring
YYYY-MM-DD: from this day on the platform may still change the numbers.
withheldboolean
True where the platform's terms keep its results inside Pluto's own app: metrics, byCurrency, breakdown and definedMetrics are null and withheldData says why.
withheldDataarray of objects
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-Withheld header 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-After seconds. 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"
GET/analytics/rankings

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformquerystringOptionalA 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.
periodquerystringOptionalA 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.
sincequerystringOptionalFirst day (YYYY-MM-DD), instead of period.
untilquerystringOptionalLast day, inclusive, with since.
metricquerystringOptionalWhat 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.
orderquerystringOptionaldesc (highest first) or asc. Default: best first, asc for costs such as cpa, cpc and cpm, desc otherwise.
limitquerystringOptionalAds per ranking, 1 to 50 (default 10).
offsetquerystringOptionalSkip this many ranked ads: the previous page's nextOffset.
minSpendquerystringOptionalOnly 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.
minPurchasesquerystringOptionalOnly ads with at least this many purchases in the period; a platform without purchases answers 422.
statusquerystringOptionalOnly ads with this status on their platform, e.g. ACTIVE (running now) or PAUSED; elsewhere also its delivery (UNDER_REVIEW, REJECTED, …).
attributionquerystringOptionalMeta's attribution setting: 7d_click_1d_view (default), 7d_click, 1d_click, 1d_view or 28d_click. Another platform takes none.
currencyquerystringOptionalOnly accounts billing in this ISO 4217 currency.
creativequerystringOptionalfalse leaves out what Creative Memory found in each ad's files (default true).
postsquerystringOptionaltrue: each Meta ad's Facebook and Instagram post links, read from Meta (the first 25 ads).
metricsquerystringOptionalThe 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).
adAccountIdquerystringOptionalRepeatable.
campaignIdquerystringOptionalRepeatable.
adSetIdquerystringOptionalRepeatable.
adIdquerystringOptionalRepeatable.
launchIdquerystringOptionalOnly ads these launches published; repeatable.
agequerystringOptionalOnly 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.
genderquerystringOptionalMeta: female, male or unknown; elsewhere female, male or undetermined; repeatable.
ageGenderquerystringOptionalMeta: <age>|<gender>, e.g. 25-34|female; repeatable.
countryquerystringOptionalISO country code; repeatable.
regionquerystringOptionalMeta: region as Meta names it; elsewhere the region's geo target ID; repeatable.
placementquerystringOptionalMeta: <platform>|<position>, e.g. instagram|reels; repeatable.
publisherPlatformquerystringOptionalMeta: facebook, instagram, audience_network, messenger or threads; repeatable.
impressionDevicequerystringOptionalMeta: device as Meta names it (iphone, android_smartphone, …); repeatable.
devicePlatformquerystringOptionalMeta: mobile_app, mobile_web or desktop; repeatable.
hourquerystringOptionalhour of the day in the ad account's time zone, 00 to 23; repeatable.
actionDevicequerystringOptionalMeta: the device an action happened on; repeatable.
actionDestinationquerystringOptionalMeta: where an action happened; repeatable.
bodyAssetquerystringOptionalMeta: a dynamic or flexible creative's text asset ID; repeatable.
titleAssetquerystringOptionalMeta: headline asset ID; repeatable.
imageAssetquerystringOptionalMeta: image asset ID; repeatable.
videoAssetquerystringOptionalMeta: video asset ID; repeatable.
callToActionAssetquerystringOptionalMeta: call to action asset ID; repeatable.
linkUrlAssetquerystringOptionalMeta: link asset ID; repeatable.
adFormatAssetquerystringOptionalMeta: ad format asset; repeatable.
productquerystringOptionalMeta: a catalog product as Meta reports product_id; repeatable.
devicequerystringOptionalWhere the platform reports it: mobile, desktop, tablet, connected_tv or other; repeatable. Other platforms' segment filters come from one breakdown at a time.
networkquerystringOptionalWhere the platform reports it: search, search_partners, content, youtube_search, youtube_watch, mixed, google_tv or unknown; repeatable.
clickTypequerystringOptionalWhere the platform reports it: the click type as the platform names it, lower case (url_clicks, call_tracking, sitelinks, …); repeatable.
slotquerystringOptionalWhere the platform reports it: search_top, search_other, content, search_partner_top, search_partner_other, mixed or unknown; repeatable.
conversionActionquerystringOptionalWhere the platform reports it: a conversion action's ID; only the conversion metrics are split by it; repeatable.
searchTermquerystringOptionalWhere the platform reports it: <search term>|<match type>, e.g. running shoes|broad; repeatable.
keywordquerystringOptionalWhere the platform reports it: a keyword's criterion ID; repeatable.
assetquerystringOptionalWhere the platform reports it: <asset ID>|<field type>, e.g. 123|headline; repeatable.
audiencequerystringOptionalWhere the platform reports it: an audience segment's criterion ID; repeatable.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

attributionstring or null
The attribution setting (Meta's; null elsewhere).
coverageobject or null
As /analytics/insights: how current the numbers are.
metricstringRequired
What the ads are ranked by.
notestring
Where the numbers show, when they're withheld.
orderstringRequired
desc: highest first.One of desc, asc
periodobjectRequired
since, until: the days ranked.
platformstring
The ad platform ranked.
postsUnavailablestring
Why the post links couldn't be read, when posts=true asked for them and they couldn't be (another platform's ads have none here).
rankingsarray of objectsRequired
A ranking per currency in scope; money never adds up across currencies.
withheldboolean
True where the platform's terms keep its results inside Pluto's own app: nothing is ranked (rankings is empty), note says where they show and withheldData why.
withheldDataarray of objects
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-Withheld header names the platforms too.

Errors

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

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.

Permission: writeCommand: send Idempotency-Key

Parameters

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

Request body

adAccountIdsarray of strings
Only these ad accounts. Every synced ad account when absent.
platformstring
A platform from GET /platforms (default: the ad accounts' platform, else the last-used connected platform).

Response202 Accepted

jobIdstring (uuid)Required
The insights import job.
queuedbooleanRequired
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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/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/analytics/reports

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformquerystringOptionalA platform from GET /platforms.
levelquerystringOptionalaccount, 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.
timequerystringOptionalsummary (default), daily, weekly or monthly, where the platform's reports take it (others answer 422 on time).
sincequerystringOptionalFirst day (YYYY-MM-DD), in each ad account's time zone.
untilquerystringOptionalLast day (YYYY-MM-DD).
adAccountIdquerystringOptionalOnly these ad accounts; repeatable or comma-separated.
formatquerystringOptionaljson (default) or csv.
limitquerystringOptionalRows in a page of a JSON answer (1-10000, default 1000).
cursorquerystringOptionalThe nextCursor of the page before, for the next page.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

columnsarray of objectsRequired
The report's columns, in order.
columns[].defaultbooleanRequired
Whether the platform asks for the column to be shown without being asked for.
columns[].idstringRequired
The column's key in every row.
columns[].kindstringRequired
text, number, money (decimal text in the row's currency) or status.
columns[].namestringRequired
The column's name as the platform's own reports call it.
dayBasisstringRequired
account: days are each ad account's own time zone days.
levelstringRequired
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.
nextCursorstring or null
The next page's cursor; null on the last page.
periodobjectRequired
period.sincestringRequired
First day.
period.untilstringRequired
Last day.
platformstringRequired
The platform the report is of.
rowsarray of objectsRequired
Highest cost first; per day, week or month the newest first.
timestring
Where the platform's reports take it: how the days came together, summary, daily, weekly or monthly.
truncatedbooleanRequired
More rows follow this page (nextCursor).

Errors

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

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformquerystringOptionalA platform from GET /platforms.
byquerystringOptionalage, gender, platforms, regions, metros, conversion_tags or placement.
campaignIdquerystringOptionalThe campaign, by its ID at the platform; optional for placement.
adAccountIdquerystringOptionalThe ad account; optional when one is connected.
sincequerystringOptionalFirst day (YYYY-MM-DD, the ad account's days).
untilquerystringOptionalLast day (YYYY-MM-DD).
countryquerystringOptionalThe platform's value for the country; needed for regions and metros.
placementquerystringOptionalThe placement a split is read on: ALL_ON_TWITTER (the default) or PUBLISHER_NETWORK.
jobIdquerystringOptionalThe job of an answer that was pending.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

bystringRequired
The segmentation asked.
currencystring
The ad account's currency (ISO 4217).
jobIdstring or null
The platform's job for this answer. Pass it back while pending.
notestring
Where the numbers show, when they're withheld.
pendingbooleanRequired
true while the platform still prepares the answer: ask again with jobId.
periodobjectRequired
since, until.
platformstringRequired
The platform asked.
rowsarray of objects or null
One row per segment: name (the platform's name for it) and metrics (the platform's own metric names, decimal strings; spend in the account's currency). Null while pending, and where withheld.
withheldbooleanRequired
The platform's terms keep what is read from it inside Pluto's own app: rows is left out here.

Errors

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