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.timezoneis the REPORTING timezone (Asia/Kolkata): the display calendar the app uses for labels and relative ranges.meta.dataTimezoneis 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.dataTimezoneis null,meta.dataTimezoneslists them andmeta.mixedTimezonesis 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 emptydataTimezonesmeans 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
moneyobject: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) andbyCurrency(the per-currency sums, one object per currency, filled only when mixed). Whenmixedis 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 andbyCurrencyis 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 setmeta.mixedCurrency. Ask per brand for a single-currency total; there is no conversion. - A
previousblock and acomparerange are resolved server-side from a named mode (previous period, previous month, previous year). Thecomparefield 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 carriesnoteson 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. |
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. |
