MetricsGo API — data contract

What every number served by /api/v1 and the MCP server means. The same text is returned by the describe_metrics MCP tool. Changing a definition is a breaking change for every consumer reading that field on a schedule — a new field is added instead.

Rules that apply everywhere

  • Meta ads days are calendar days in the AD ACCOUNT's own timezone (Asia/Kolkata for every account connected so far) and organic social days are calendar days in Asia/Kolkata (IST, UTC+5:30); an IST day runs 00:00:00–23:59:59.999 IST. The Google and Shopify surfaces keep the source platform's own day boundary: GA4 days are in the Analytics property's timezone, Search Console days are Pacific, and Shopify days are in the shop's timezone. Those three will not line up with each other or with IST, and none of them is wrong — each response reports the timezone of the assets behind it.
  • Two timezones ride on every response and they are not the same thing. meta.timezone is the REPORTING timezone (Asia/Kolkata): the display calendar the app uses for labels and relative ranges. meta.dataTimezone is the DATA CALENDAR: the timezone the rows are bucketed in — the GA4 property's, the Google Ads or Meta ad account's, the Shopify shop's, America/Los_Angeles for YouTube and Search Console, Asia/Kolkata for organic social, competitor changes and the add-ons. When the assets in scope use different calendars, meta.dataTimezone is null, meta.dataTimezones lists them and meta.mixedTimezones is true: the response then sums rows that do not share a day boundary, so day-level comparisons across it are approximate by construction — ask per brand for an exact one. An empty dataTimezones means no asset of that kind is in scope.
  • null is ABSENCE — the platform did not report the metric — and is never a zero. A genuine zero is 0.
  • Ratios are null when their denominator is zero: no CTR without impressions, no cost per result without results.
  • Numbers come from stored data synced by MetricsGo. meta.syncedAt is the NEWEST successful sync among the assets in scope; meta.freshness (where present) is the honest aggregate: status fresh / partial / stale / never, oldestSuccessAt, every asset’s lastSuccessAt, lastAttemptAt, lastAttemptStatus and coveredTo, and the ids of the assets that are behind (incomplete). The API never calls Meta on your behalf.
  • Currency amounts are in the ad account's own currency (meta.currency), major units, unrounded.
  • Money is never added across currencies. Every block that sums money (Meta ads, Google Ads, Shopify, GA4 revenue, GoKwik) carries a money object: currency (the one currency every amount is in), currencies (the distinct currencies of the assets in scope), mixed, unknown (assets or orders with no currency on record — never assumed to match a labelled one) and byCurrency (the per-currency sums, one object per currency, filled only when mixed). When mixed is true, every money total and every money-derived rate in that block (spend, cost, sales, revenue, CPC, cost per conversion, ROAS, AOV, revenue per session or customer, including the daily series and breakdown rows) is null and byCurrency is the figure to show; counts are unaffected. Rows that belong to one asset (a Meta or Google Ads campaign) keep their money and say which currency it is in. MCP responses also set meta.mixedCurrency. Ask per brand for a single-currency total; there is no conversion.
  • A previous block and a compare range are resolved server-side from a named mode (previous period, previous month, previous year). The compare field on the response is the exact window those numbers cover.
  • Google Ads days are the ad account’s own timezone and YouTube Analytics days are Pacific, like Search Console. Google Ads cost is in the account’s currency. Google Ads and Meta ads are separate platforms with separate attribution: their spend, clicks and conversions are never added together.
  • Competitor data is what MetricsGo read from competitors’ PUBLIC websites on its scheduled checks (catalogue, prices, stock, banners, promo codes, pixels, SEO). It is not the competitor’s ad spend, traffic or sales. Change days are the IST day a check detected the change, not the day the competitor made it.
  • Meta has retired several Facebook Page metrics (Page reach, Page impressions, post reach, post impressions). They are null for Facebook, permanently, and are documented as such rather than omitted.
  • Client add-ons (GoKwik checkout, Zoho Books) exist only for the brands that have them enabled (list_clients addons); for any other brand the add-on endpoints answer the same not-found as an unknown brand. Their dates are IST calendar days, their amounts are rupees, and each response carries notes on how to read it.

Ads (ads:read)

Field Unit Definition null means
spend currency Amount spent in the range, summed from daily rows. The scoped accounts bill in different currencies (money.mixed); see money.byCurrency.
impressions count Times an ad was on screen, summed from daily rows. —
reach count People who saw the ad at least once. Summed over daily rows, so across many days it is an upper bound — Meta de-duplicates reach within a single insights window, and daily rows are separate windows. —
clicks count All clicks (Meta clicks), summed. —
linkClicks count Clicks on links in the ad (Meta inline_link_clicks), summed. —
results count The action Meta counts as this entity's result: the ad set's promoted_object (a custom conversion or standard pixel event) first, then the optimisation goal, then the campaign objective. Matches the Results column in Ads Manager for the same attribution setting. No result definition applies (e.g. account level, or an objective with no countable result).
resultType label The Meta action_type that results counts (e.g. offsite_conversion.custom., purchase, link_click). In the overview it is the ONE type every campaign in scope shares. In the overview, null with results > 0 means the range mixes result types (e.g. leads and video views); that total is a sum of unlike things and must not be compared across campaigns — narrow to a brand or campaign. Elsewhere: no result definition.
ctr percent clicks / impressions × 100. No impressions.
cpc currency spend / clicks. No clicks, or mixed currencies.
costPerResult currency spend / results. No results, no result definition, or (overview) the range mixes result types — there is no single thing to price.
frequency ratio impressions / reach. No reach.
account label The ad account the row belongs to: { id, platformAccountId (Meta act_… id), name }. On every entity row and every overview campaign. Join key to /v1/clients. The account is no longer connected.
client label The MetricsGo brand that account is assigned to: { id, name }. A brand is called a client in the API and MCP tools for backwards compatibility. This is how a row is attributed to a brand. When the account is not assigned to a brand, name falls back to the account name and id is null. The account is no longer connected (same as account).
campaign label Parent campaign of an ad set or ad: { id, platformId (Meta campaign_id), name, objective }. Campaign-level rows have no parent campaign.
adSet label Parent ad set of an ad: { id, platformId (Meta adset_id), name }. Only ads have a parent ad set.
videoViews count 3-second video plays (Meta video_play_actions), summed. —
purchaseValue currency Sum of purchase conversion value (Meta action_values for purchase). 0 when never reported. Mixed currencies (money.mixed).
previous count Totals for the period of the same length immediately before from, with the same entity scope. 0 where the previous period had no data for that metric. —
funds.balance currency Money left to spend, summed over scoped accounts: the remaining spend limit (spend cap minus amount spent) or prepaid funds where Meta shares them. Never the unbilled amount owed. No scoped account has a spend limit or shared prepaid funds, or the accounts use different currencies.
funds.cap currency Spend cap summed over scoped accounts that have one. No scoped account has a cap.
breakdowns.*.reach count Reach within one breakdown slice. NOT additive across slices — one person can appear in several. —
stale label Breakdowns only. True when the dashboard would refetch this range from Meta; the numbers may lag until someone opens the entity in the dashboard. —
compare label Overview only. The window previous covers, resolved server-side from the compare argument (previous = the equal-length period immediately before, prevMonth, prevYear, none). Existing callers get previous, unchanged. compare=none: no comparison was read, and previous is null too.
`sort dir` label Entities only. The order the rows come in, as the Explore table sorts them (spend desc by default): a metric key orders in SQL before the 500-row cap, so the page is the top 500 BY THAT KEY; name and delivery order the 500 highest-spend rows. Nulls sort last whichever direction.
merchantAccounts label Clients only. The Google Merchant Center accounts assigned to the brand: merchantId, name, lastSyncedAt and registrationStatus (null = Google serves data; registering or needs_admin = attached but not yet readable). connected.merchantCenter is the boolean. —

Social (social:read)

Field Unit Definition null means
reach count Accounts reached, summed over daily rows in the range. Not reported. Permanently null for Facebook Pages (retired by Meta).
impressions count Retired by Meta for Facebook Pages and never served for Instagram accounts; kept for shape compatibility. Always null.
views count Instagram views (the metric that replaced impressions), summed. —
profileViews count Instagram profile views, summed. Not reported; permanently null for Facebook.
interactions count Instagram total interactions / Facebook page post engagements, summed. —
newFollows count New follows in the range, summed. —
followers count Follower count at the latest day in the range that has a reading. Point-in-time, not a sum. No reading in the range.
engagementRate percent interactions / reach × 100. Either side missing, or reach is 0.
postTotals.newPosts count Posts published in the range (IST). Always a real count. —
`postTotals.likes comments shares saves`
posts[].engagementRate percent (likes + comments + shares + saves) / reach × 100 for one post. Reach is null or 0.
posts[].thumbnailHref label URL of the stored thumbnail on this API, requires the same API key. No thumbnail stored.
compare label Overview only. The window previousTotals and previousPostTotals cover (also echoed as previousFrom / previousTo), resolved server-side from the compare argument: previous (default, the equal-length period immediately before), prevMonth, prevYear or none. compare=none: previousFrom, previousTo and every previous block are null.

Website — Google Analytics and Search Console (web:read)

Field Unit Definition null means
analytics label The Google Analytics block, with the properties behind it. Null means no Analytics property is attached to the brands in scope — "not connected", not "no traffic". No GA4 property attached.
sessions count GA4 sessions, summed over daily rows. The honest volume metric for a range. —
totalUsers count Sum of GA4’s DAILY unique users. Somebody who visits on Monday and again on Friday is counted twice, so over a range this is an upper bound on distinct people, not a headcount. —
activeUsers count Sum of GA4’s daily active users. Same daily-sum caveat as totalUsers. —
newUsers count Users whose first session ever fell in the range, summed daily. —
engagedSessions count Sessions GA4 counts as engaged (over 10 seconds, a key event, or 2+ pageviews), summed. —
engagementRate ratio engagedSessions / sessions, 0–1 (not a percentage). Recomputed over the whole range, never an average of daily rates. No sessions.
bounceRate ratio 1 − engagementRate, 0–1. GA4 defines a bounce as a session that was not engaged — it is not the old Universal Analytics single-pageview bounce. No sessions.
averageSessionDuration ratio Seconds per session, weighted by sessions over the range (Σ(duration × sessions) / Σ sessions). No sessions.
screenPageViews count Page and screen views, summed. —
eventCount count All GA4 events, summed. —
keyEvents count Events marked as key events (conversions) in the property, summed. Which events count is the property owner’s configuration, not ours. —
conversionRate ratio keyEvents / sessions, 0–1. This product’s one definition of website conversion rate. No sessions.
totalRevenue currency GA4 total revenue in the property’s currency (meta.currency), summed. The properties in scope report in different currencies (analytics.money.mixed); see money.byCurrency.
purchaseRevenue currency GA4 purchase revenue only, summed. Not reconciled with Shopify: GA4 attributes on its own day boundary and only sees what the tag fired. —
transactions count GA4 transactions, summed. Will not equal Shopify orders — different timezone, different definition, and GA4 misses what the tag did not see. —
revenuePerSession currency totalRevenue / sessions. No sessions.
`channels sources landingPages pages
organicLandingPages label Entry pages counting ORGANIC SEARCH sessions only. Not a subset of landingPages, whose rows include paid, social and direct traffic to the same page. —
partial label True when GA4 collapsed part of at least one breakdown into its "(other)" row, so the tables do not add up to the totals. Cardinality limits in GA4, not missing data. —
properties[].timezone label The Analytics property’s reporting timezone — the day boundary every GA4 number here uses. Not reported by the property.
search label The Search Console block. Null means no Search Console site is attached to the brands in scope. No Search Console site attached.
search.clicks count Clicks from Google search results to the site, summed over days. —
search.impressions count Times a link to the site appeared in search results, summed over days. —
search.ctr ratio clicks / impressions, 0–1. Recomputed over the range. No impressions.
search.position ratio Average position: a RANK, so LOWER IS BETTER — 4.1 beats 8.4. Weighted by impressions (Σ(position × impressions) / Σ impressions), never a plain average: a query seen 10,000 times at rank 3 and one seen twice at rank 90 do not average to 46.5. No impressions.
search.positionWeighted ratio Σ(position × impressions), exposed so a consumer can re-weight a subset of rows correctly instead of averaging positions. —
search.queries label Top queries by clicks. These rows DO NOT SUM to the site totals: Google withholds queries too few people searched, so query clicks and impressions are always less than the site total. The gap is expected and is not missing data. —
`search.pages countries devices appearances`
search.searchType label Which Search Console surface the numbers cover: web (default), image, video, news, discover or googleNews. Types are separate indexes and do not add up to a grand total. —
sites[].firstIncompleteDate label The first day from which Google’s own data for this site is still settling — numbers on and after it can still rise. Google reported nothing pending.
search.days label Search Console days are PACIFIC time, unlike GA4 (the property’s timezone) and Shopify (the shop’s). The three sources will not line up day for day. —

Store — Shopify (store:read)

Field Unit Definition null means
store label The Shopify block, with the connected shops behind it. Null means no store is connected for the brands in scope. No Shopify store connected.
grossSales currency Product price × quantity, BEFORE tax, shipping and discounts, and INCLUDING cancelled, pending and unpaid orders. Shopify’s own definition; it is not "money received". —
discounts currency Discounts applied in the range, as a positive number subtracted from gross sales. —
returns currency Refunded value, DATED ON THE REFUND rather than on the original order. A refund can push a day’s net sales negative and never reduces the day the order was placed. —
netSales currency grossSales − discounts − returns. Still EXCLUDES shipping and tax. The stores in scope sell in different currencies (store.money.mixed): every money figure in the block is null and money.byCurrency has the per-currency ladder.
`shipping taxes duties tips`
totalSales currency netSales + shipping + taxes + duties + tips. The bottom line of Shopify’s own finance summary. —
orders count Orders placed in the range, including cancelled and unpaid ones (consistent with grossSales). —
cancelledOrders count Orders cancelled, counted on the order’s own day. Included in orders, not subtracted from it. —
refundedOrders count Orders with a refund, counted on the refund’s day — the same dating rule as returns. —
unitsSold count Line-item quantity summed over orders in the range. —
`customers newCustomers returningCustomers` count
averageOrderValue currency netSales / orders, recomputed over the whole range. Never an average of daily averages — a Tuesday with two orders must not weigh as much as a Saturday with two hundred. No orders, or mixed currencies.
averageUnitsPerOrder ratio unitsSold / orders. No orders.
returnRate ratio returns / grossSales, 0–1. Because returns are dated on the refund, a short range can show a rate above 1. No gross sales.
discountRate ratio discounts / grossSales, 0–1. No gross sales.
newCustomerRate ratio newCustomers / customers, 0–1. No customers.
revenuePerCustomer currency netSales / customers. No customers.
`products channels referrers countries
sessions count DOES NOT EXIST. Shopify’s Admin API reports no sessions and no store conversion rate, so neither is served here. Say the data is unavailable rather than deriving one from ad clicks or GA4 sessions — those measure different populations. Never present; the field is absent entirely.
stores[].timezone label The shop’s own reporting timezone — the day boundary every Shopify number here uses. It will not match GA4 (the property’s) or Search Console (Pacific). Not reported by the shop.
hasAllOrdersScope label False means Shopify granted only the last 60 days of order history for this shop, so earlier days are genuinely absent rather than zero. —

Google Ads (ads:read)

Field Unit Definition null means
ads label The Google Ads block, with the accounts behind it. Null means no Google Ads account is attached to the brands in scope — "not connected", not "no spend". No Google Ads account attached.
ads.currency label The currency every Google Ads amount is in: the accounts’ own currency. The accounts in scope use different currencies (ads.money.mixed), so no single total is meaningful; ads.money.byCurrency has the per-currency cost and conversion value; ask per brand.
cost currency Google Ads spend (cost_micros / 1e6), summed over daily rows, in the account currency. Mixed currencies (ads.money.mixed): cost, conversionsValue, averageCpc, costPerConversion and roas are null in totals, series and breakdowns; campaign rows keep theirs with their own currency.
`impressions clicks interactions videoViews`
conversions count Conversions as Google Ads counts them for bidding (the "Conversions" column), summed. A decimal: Google credits fractions of a conversion under data-driven attribution. —
allConversions count Every conversion action, including ones excluded from bidding ("All conv."), summed. —
conversionsValue currency Value of conversions, in the account currency. —
averageCpc currency cost / clicks over the whole range. No clicks.
costPerConversion currency cost / conversions over the whole range. No conversions.
roas ratio conversionsValue / cost — a multiple: 2.4 means 2.40 back per 1 spent. No cost.
viewRate ratio videoViews / impressions, 0–1; meaningful for video campaigns only. No impressions.
`ctr conversionRate` ratio clicks / impressions and conversions / clicks, 0–1, recomputed over the range.
`channelTypes devices networks conversionActions`

YouTube (social:read)

Field Unit Definition null means
youtube label The YouTube block, with the channels behind it. Null means no channel is attached to the brands in scope. No YouTube channel attached.
views count Video views from YouTube Analytics, summed over Pacific days. —
estimatedMinutesWatched count Watch time in minutes (YouTube’s estimate), summed. —
averageViewDurationSeconds ratio estimatedMinutesWatched × 60 / views over the whole range — weighted by views, never an average of daily averages. No views.
`subscribersGained subscribersLost netSubscribers` count
channels[].subscriberCount count The channel’s subscriber count at the last sync — a snapshot, never a sum over the range. The channel hides its subscriber count.
`trafficSources devices countries` label

Competitor intel (any key)

Field Unit Definition null means
productsTracked count Live products the checks currently read on the competitor’s site. —
severity count How loud a change group is, 1 (minor, e.g. an SEO title edit) to 5 (major, e.g. a site-wide sale). The dashboard feed shows 3 and up by default. —
headline label One-line summary of a change group, e.g. "12 prices cut, average −18%". —
items label Up to three example changes behind a group (label, before, after, product photo); count is how many there are in total. —
insights label Rule-based observations (no AI): share on sale and its weekly move, launches, price cuts, sell-outs, new banners, promo codes, new pixels. Only emitted when the stored history supports them. —
avgDiscount ratio Mean discount of the products on sale (1 − price / compare-at price), 0–1. Nothing on sale.
priceMoves label The largest price changes over the last 90 days: the price a product entered the window at versus now, with the signed fraction pct. In the competitor’s currency. —
days count The Competitors page’s period, 1–90 (default 1), on list_competitors and get_competitor_insights: 1 is the last 24 hours exactly (rolling), more is that many IST calendar days including today. It sets window and the per-site change counts; it never filters the roster or the insights. —
check label One site’s check state as the Competitors page’s chips show it: state (changed = at least one change group of any severity in window; checked_no_changes; partial = the latest successful check could not read everything; failed; stale = no successful check in 48 hours; paused; unsupported = needs a browser; pending = first check not finished), the newest attempt and newest success, and changeGroupsInWindow / changeEventsInWindow. —
window label The period a count was measured over: kind (rolling or ist_days), days, from and to as ISO instants, fromDay as the IST day from falls on. —
logoUrl label The competitor site’s logo as the checks found it — a URL on the competitor’s own site. No logo was found.
`bannersTotal bannersLiveBySite` count Insights only. Every live banner across the competitors in scope, uncapped, and the same per competitor id; stats.bannersLive on the detail is the same count for one site.
total count Changes: { groups, events } at or above minSeverity in the range over every page (events are the individual changes). With group: the number of changes in that group. —
`nextCursor cursor` label Opaque keyset cursor for the next page of groups, of one group’s changes, or of a detail dataset (there as page.nextCursor); pass it back as cursor. The same paging the dashboard uses.
group label Changes with group (a group id from a page): that group’s full change list — { group, changes[], total, nextCursor }. Each change has its type, entityKey (the product handle, page path or image URL), severity, label, before and after. from/to are ignored; a group outside the key’s brands is the same 404 as an unknown id. —
datasets label Detail without dataset: the full lists behind the capped summary — products, price_history, banners, seo, runs — each with its total and page size. The summary itself is capped at 12 live banners, 10 price moves, 20 collections and 5 checks. —
dataset label Detail with dataset: one page of that list as { competitor, dataset, page: { total, shown, offset, nextCursor }, items }. products = every live product (up to 500 per page; price, compareAtPrice, the product’s own currency or null, availability, variants, gallery, tags, productType, vendor, sku, publishedAt, categoryPath, collections, lastChangedAt); price_history = the same products with history, the price steps over the last 90 days plus the price the product entered the window at; banners = every banner ever seen, removed ones included (removedAt null = still live; up to 60); seo = title, description and heading edits per page URL, newest first (up to 100); runs = the check log with trigger, status, times, counts and a plain-language error (up to 30). limit is clamped to the page size. —
scope label list_competitors and get_competitor_detail: which sections of the site the checks watch. mode whole_site = everything (items empty); selected = only items (kind collection = a Shopify collection handle, path_prefix = a URL path such as /men/shirts/), with sitewide saying whether homepage banners, SEO and site facts are watched too. missing = the section no longer exists on the site. Products outside the scope are hidden from every count and list; changes recorded before the scope narrowed stay in the feed. —
items[].currency label A product’s own currency as stored on the competitor’s site. The site did not say; do not assume competitor.currency for that product.

GoKwik checkout add-on (store:read, brands with the add-on only)

Field Unit Definition null means
checkoutsStarted count Unique checkouts that fired GoKwik’s started-checkout event in the range, counted by cart token. Only since the pixel was installed. —
ordersPlaced count Unique checkouts that reached order placed, by cart token (or order id when the event has no cart token). —
conversionRate ratio ordersPlaced / checkoutsStarted, 0–1. No checkout started in the range.
`revenue averageOrderValue` currency Sum and mean of the placed orders’ amounts, in currency (rupees unless the pixel says otherwise). Amounts on steps before the order is placed are the cart value.
codShare ratio Share of placed orders paid cash on delivery, 0–1. No orders.
`funnel[].stepConversion dropOff` ratio Share of the previous step’s checkouts that reached this step, and 1 minus that.

Zoho Books add-on (store:read, brands with the add-on only)

Field Unit Definition null means
sales currency Totals of issued invoices dated in the range, INCLUDING tax, in rupees. —
collections currency Customer payments recorded in Zoho Books in the range. Only what someone recorded; see lastPaymentDate. —
`outstanding overdue` currency Unpaid balance on issued invoices as of today (asOf), and the part past its due date. Independent of the range.
expenses currency Recorded expenses plus vendor bills dated in the range. —
grossProfit currency Zoho’s P&L gross profit summed over the whole months that overlap the range (grossProfitMonths); excludes tax. No P&L month synced for the range.
books label The Zoho Books figures for the selected organization(s). Not connected or not synced yet.

Brand overview and roster (ads:read + social:read + web:read + store:read)

The Overview page and the agency roster span every surface, so both need every scope. Each card or cell is ONE platform’s own numbers in that platform’s currency and day boundary; nothing is summed across platforms or brands, and Shopify revenue ÷ ad spend is not a ROAS. meta.dataTimezone is null with mixedTimezones true whenever the connected platforms keep different calendars.

Field Unit Definition null means
sources.<platform>.status label One of ready, no_activity (connected, no rows in the range), not_connected, stale (past the platform’s freshness policy: 26 h for Meta, Google Ads, social, YouTube and Shopify, 30 h for GA4, 72 h for Search Console), partial (GA4 collapsed rows into "(other)", or Shopify serves only 60 days of orders) or failed (that source did not answer; the rest of the page is unaffected). Every supported platform appears, connected or not. —
sources.<platform>.syncedAt timestamp The OLDEST successful sync among the assets behind that platform’s card, so one fresh account cannot hide a stale one; sources.<platform>.freshness lists each asset’s own status (state fresh / stale / never). A source with any asset behind or never synced is stale. Never synced, or not connected.
sources.<platform>.timezoneNote label The calendar the platform’s days are in: an IANA zone when one applies, otherwise a phrase such as "mixed account time zones". —
sources.<platform>.coverage label The days the range actually has rows for, present only when that is less than the whole range. —
cards[].kpis[] label The platform’s headline numbers: { key, label, value, previous, delta, direction, verdict, format, currency, source, definition }. delta is a proportion (0.12 = +12%); direction says which way is good (up-good, down-good, neutral); verdict is good, bad or flat for THIS movement; definition is the one-sentence meaning of the number. value: the platform did not report it. previous: no rows in the comparison window, or compare=none. delta: either side unknown or previous is 0.
cards[].series[] label One point per day: volume (what went in — spend, sessions, impressions, orders) and outcome (what came of it — results, key events, clicks, net sales); seriesKeys names the two. A day the platform did not report.
cards[].highlights label The platform’s own top few things in the range (campaigns, posts, videos, landing pages, queries, products): columns, rows with typed cells, and a footnote for any judged (chip) column. thumbnailHref is a URL this key can fetch. —
outcomes[] label The business questions (paid, audience, search, website, commerce), each answered by every connected platform that can — as separate entries, never one added-up number — with missing naming the connectable platforms the brand lacks. —
movers[] label The KPIs that moved most, across platforms, each with its sentiment; ranked only among KPIs whose volume clears a floor in both periods. —
signals[] label Up to five Meta ads signals (see Ads signals). Empty when Meta is not connected. —
attention[] label What needs a person: low_balance, expired_connection, stale_data, partial_permissions, sync_failed, each with a severity (info, warning, critical), a title, a detail sentence and an app link. —
competitors label Present only when the brand watches at least one competitor site: sites watched, changes detected TODAY (IST) whatever the range, the loudest severity and a highlights table. Absent when nothing is watched.
rows[].cells label Roster: one cell per connected platform, keyed metaSpend, metaResults, gadsSpend, gadsConversions, igReach, fbInteractions, ytViews, ga4Sessions, gscClicks, shopifyNetSales, each a KPI as above. A missing key is a platform that is not connected. value: connected, but no rows in the window.
sources.<platform>.freshness label Per-asset sync status behind that card: status (fresh / partial / stale / never), oldestSuccessAt, newestSuccessAt, assets[] (id, kind, name, lastSuccessAt, lastAttemptAt, lastAttemptStatus, coveredTo, state) and incomplete (ids of assets that are behind). Same shape as meta.freshness. Absent when the source is not connected or failed.
rows[].freshness timestamp Roster: the OLDEST last successful sync among each connected platform’s assets (one fresh account never hides a stale one); an asset that never synced raises a sync_failed attention item instead. Never synced.
rows[].health label Roster: attention when any item needs a person (anything but stale_data), stale when only staleness, else ok. Rows sort attention, stale, ok, then by name. —

Ads signals (ads:read)

Field Unit Definition null means
signals[] label Campaigns, ad sets or ads whose metric moved unusually between the range and the previous period of equal length. "Unusual" is derived from the data itself: the entity’s percent change sits at least 3 median absolute deviations (score) from the median change of its siblings AND the change is at least 10%. No fixed thresholds exist — no "frequency above 3" or "CTR under 1%" rule. Ranked by score. —
signals[].metric label One of hookRate, holdRate, lpvRate, ctr, cpc, costPerResult, frequency, results, spend. Rates are percentages; money is in the entity’s ad account currency (signals[].currency). —
signals[].changePct percent (current − previous) / previous × 100. Never null: a signal is only built from two reported values with a non-zero baseline. —
signals[].sentiment label Whether the movement is welcome: a FALL in cpc, costPerResult or frequency is good; a fall in hookRate, holdRate, lpvRate, ctr or results is bad; spend is neutral. —
comparedEntities count Entities present in BOTH windows with a row each. 0 means the windows do not overlap — not "nothing unusual". A metric also needs at least 5 entities clearing its volume floor in both periods before anything can be unusual. —
truncated label True when more signals existed than limit (default 50) returned. —

Budget pacing (ads:read)

Field Unit Definition null means
pacing label The pacing block for the scoped Meta ad accounts: the IST calendar month to date, whatever range other tools were asked for (meta.from/meta.to are the month start and today). No Meta ad account in scope.
spend currency Month-to-date spend at account level, in currency. 0 is a real zero. —
budget currency The month budget, resolved in preference order; budgetSource says which won: adset-daily (Σ active ad-set daily budgets × days in month), adset-lifetime (Σ active ad-set lifetime budgets, taken as-is, not pro-rated), account-spend-cap (Σ account spend caps — a lifetime cap, a coarse last resort). Paused ad sets never count. No source exists. Never 0 — every budget-derived ratio is then null too.
budgetUsedPct percent spend / budget × 100. No budget.
projectedSpend currency The run-rate: spend ÷ days elapsed (today counts as elapsed) × days in the month. Before the month starts.
projectedVsBudgetPct percent (projectedSpend − budget) / budget × 100, signed. No budget.
`dailyPaceSoFar idealDailyPace requiredDailyPace` currency
status label on_track when the projection is within ±5% of budget, under below that, over above it, unknown without a budget. A display band, not a performance judgement. —
currency label The scoped accounts’ currency. The accounts disagree or it is unknown.