Supermetrics

Tools 15

• Data Query

  Query data from Google Ads, Facebook Ads, Google Analytics, LinkedIn Ads, TikTok Ads, Microsoft Ads, Shopify, HubSpot, and 200+ other platforms. Use data_source_discovery, accounts_discovery and field_discovery first. Returns rows when completed; else pass schedule_id to get_async_query_results. Team- and data-source-level context arrives with data_source_discovery/accounts_discovery, and a narrowed accounts_discovery (≤3 accounts) inlines an account's own context — apply what you already have. Only when you are querying a specific account whose context you have not seen, read it first with manage_business_context (action 'get', ds_id + account_id) for reporting guidelines — e.g. which campaigns to exclude, how to segment data, preferred metrics. If the user specifies reporting preferences during the conversation (e.g. "exclude brand campaigns", "always break out Advantage+ separately", "for this client we only look at last-click attribution"), ask whether to save these as context for future sessions using manage_business_context with action 'save'.

• Get Async Query Results

  Retrieve results from a data_query using its schedule_id. Call immediately; the call waits, so it usually returns data first time. While pending, call again immediately; stop when status is 'completed' or failed. Map columns by requested_field_ids/canonical_field_ids, not the row-0 display names.

• Data Source Discovery

  Discover data sources or get a source's configuration. Without ds_id: lists all sources with auth status. With ds_id: returns config (capabilities, report_types, settings, login link if needed). With filter: narrows the list; single match returns full config automatically.

• Accounts Discovery

  Discover connected accounts for a data source. Only call if data_source_discovery config shows has_account_list=true. RETURNS: account_id, account_name, group_name (when present), tags (when present), and saved business context for an account when present: in a narrowed result (≤3 accounts) the context text is inlined as `context`; in a larger list only `context_tags` are shown — fetch that text with manage_business_context get, ds_id + account_id, filtered by tag.

• Field Discovery

  Discover available fields (metrics and dimensions) for a data source. Only call if data_source_discovery config shows has_fields=true. Fields in a query must share a common report_type if the source uses report types.

• Get Today

  Get current UTC date and time. Use before data_query with custom date ranges to resolve relative date references (e.g. "last month") into specific dates.

• Instagram Insights

  Instagram and Facebook (Meta) social media analytics and insights, using the same parameters and result format as data_query. Returns rows when completed; otherwise pass schedule_id to get_async_query_results. Metrics include engagement, engagement rate, reach, accounts reached, accounts engaged, followers, fans, follower growth, impressions, profile and page views, website and link clicks, top posts and best-performing content, content performance, stories, reels, video views, saves, likes, comments, shares, and audience demographics. Data sources (pass one as ds_id): - "IGI" — your connected Instagram business/creator account insights (media, reels, stories, top posts, follower demographics); - "IGPD2" — public data on any Instagram profile or hashtag (competitor benchmarking, business discovery, hashtag search); - "FB" — organic Facebook Page insights (page and post engagement, reach, fans/followers, impressions); - "FA" — Facebook & Instagram paid ad performance (Meta Ads); add the "publisher_platform" dimension to separate Facebook from Instagram placements (values include facebook and instagram; filter or segment on publisher_platform = instagram for Instagram-only ad metrics). Then use accounts_discovery to find the account IDs to pass in ds_accounts, and field_discovery to find the available field/metric IDs (and report types) for your chosen ds_id. To create or update Instagram (or Facebook) ad campaigns, use the manage_campaign tool. For any other platform (Google Ads, GA4, LinkedIn Ads, TikTok, and 170+ other data sources), use the data_query tool.

• Manage User And Team

  Manage your Supermetrics account: user and license info, team members and invites, data-source login links, subscription user assignment, and viewing or changing a data source prioritised (pinned) accounts with the cap and monthly change quota. Operations: get_info; invite_member; login_data_source (ds_id); add_user_to_subscription (license_id, user_ids); get_prioritised_accounts (ds_id); set_prioritised_accounts (ds_id, account_ids). Use get_info to find license_id and team member user_ids.

• Contact Supermetrics

  Send feedback, create a support ticket (only when the user authorizes it), or submit a sales enquiry. For a common problem, first call supermetrics_guide and try the relevant steps before opening a ticket. Only ticket if that does not resolve it or it needs staff action (refunds, cancellations, trial extensions, non-self-serve plan changes, or a genuine bug); if you do, note which guide was tried and what still failed. For product feature requests, you can also point users to the public wishlist at https://wishlist.supermetrics.com, where they can submit and vote on ideas. For standard purchases, direct users to buy online at https://supermetrics.com/pricing. Only submit a sales enquiry for special needs: many data sources, data source accounts, users, or other custom requirements. You can also check on existing support tickets: use type "ticket_status" (no ticket_id to list your tickets, or with a ticket_id to read its replies) and type "ticket_reply" to post a follow-up. Only your own tickets are accessible, and only post a reply when the user explicitly asks. Before creating a support ticket, first call type "ticket_status" (no ticket_id) to list the user's existing tickets and check whether an open one already covers the same issue. If it does, add to that ticket with type "ticket_reply" instead of creating a duplicate; only create a new ticket when none of the open tickets match.

• Manage Business Context

  Store and retrieve durable business context — guidelines, policies, and preferences a team wants applied consistently and shared with all members. Context can cover reporting conventions, analysis rules, brand and tone, data governance, naming, plans, or account-specific preferences. Stored at three scopes, each read independently (a `get` returns one scope's context, not a merge): - **Team** — applies everywhere (e.g. "report currency in EUR"). - **Data source** — a specific platform (e.g. "for Meta, break out Advantage+ separately"). - **Account** — a specific account (e.g. "this client reports last-click only"). **Actions:** - `get` — Retrieve context by scope, chosen by the ids (no cascade): no ids → team-level; `ds_id` → that data source's level; `ds_id`+`account_id` → that account's level. `tags` filters by tag — a record matches if it carries **any** of the tags you pass (OR); commas are just separators, so `tags: ["a,b"]` and `["a","b"]` both match records tagged a or b — handy for fetching several clients at once (e.g. one client tag per client, then `["acme,globex"]`). Omit `tags` to read all entries at the scope, and **`tags` with no ids searches across all scopes**, so a tag lookup isn't confined to one level. Returned grouped as `team`/`data_source`/`account` (empty omitted); a single-source data-source list is keyed `data_source:<ds_id>` (e.g. `data_source:AW`). To assemble everything applicable to an account, read the levels separately — or rely on the discovery tools, which surface applicable context automatically. - `save` — Create/update at a scope; needs `context_text` and `tags` (a tag can't contain a comma). Tags identify the entry within a scope, so a scope can hold several entries (one per tag set): `mode: "replace"` (default) overwrites the entry with those tags, `mode: "append"` concatenates to it, and a different tag set is saved as a separate entry rather than overwriting. - `delete` — Remove the single entry identified by scope (`ds_id`/`account_id`) **and** `tags` — it targets that one tag set, never the others at the scope. Omit `tags` to remove the untagged entry. Irreversible, so confirm first. **When to save:** when the user shares a plan, guidelines, or SOP; states a durable preference ("for this client, always…"); or corrects your approach — offer to save it so it applies in future sessions. Distill the key, reusable rules — do not store documents verbatim — and tag them (e.g. "data-analysis", "targeting", "naming-conventions", "brand-visuals", "brand-language"). Tags are how you retrieve an entry later — use category tags, or, to group context the scope can't (an agency client that spans several accounts and platforms), the client's name: a team-level entry tagged with a client name that maps the client to its accounts is a good pattern. Avoid tags that merely restate the scope (a data-source entry's own data source, an account's own id). **When to read:** prefer what the discovery tools already surface — `data_source_discovery` and `accounts_discovery` include team- and data-source-level context in their responses, and a narrowed `accounts_discovery` (≤3 accounts) inlines an account's own context. Call `get` only for a scope a discovery response did not cover — e.g. an account you are about to act on that was not in a discovery result — or to re-read after you `save`. Apply context when selecting metrics, filtering data, forming recommendations, or making changes.

• Manage Dashboards

  Share live dashboards in Supermetrics Studio — self-contained pages that re-query the user's data on each view, so a shared link always shows current numbers. Before uploading, show a STATIC inline preview (data hard-coded, no smQuery), then confirm before uploading the LIVE smQuery version. smQuery and window.fetch work only inside Studio, so a preview using them renders empty in the chat — the inline preview must hard-code the data you already fetched, and the upload must fetch via smQuery (see the 'code' param), never the hard-coded preview. ALWAYS offer this upload after building a dashboard — it is how users discover Studio; do not just show the preview and stop. Skip the confirmation only when the user EXPLICITLY asked to publish (e.g. "put this in Studio and give me a link"). Actions: - 'upload': Upload a new dashboard or replace an existing one. Requires title, code, allowed_tools, allowed_accounts; description is optional. The code format (HTML or JSX) is detected automatically. - 'get': Retrieve a dashboard's source code and metadata by ID. Use this to load current code before editing. - 'edit': Apply targeted anchor-based patches to dashboard code. Call 'get' first to see the current code, then send patches. - 'changelog': View version history with change descriptions. Edit patch types (pick the smallest that fits): - region replace (PREFER for changing a section's logic/content): {"from": "// #region charts", "to": "// #endregion charts", "replace": "// #region charts\n<new code>\n// #endregion charts"} — replaces the WHOLE region from 'from' to 'to', anchor lines INCLUDED. Write the COMPLETE new block in 'replace' and reproduce the 'from' and 'to' marker lines inside it (normally unchanged) so they survive; omitting a marker deletes it. Restating an anchor does NOT duplicate it. 'from' must be unique; 'to' is the first match after it. - find/replace (small unique swap): {"find": "old text", "replace": "new text"} - after/insert (a NEW element): {"after": "anchor text", "insert": "new content"} - before/insert: {"before": "anchor text", "insert": "new content"} Modifiers (find/replace only): "nth": N (target Nth occurrence), "all": true (replace all). Patches are applied sequentially and atomically. Patchable code: When uploading, wrap each section in PAIRED region markers so edits can target them, and declare each variable/function inside the region that uses it: - HTML: <!-- #region header -->…<!-- #endregion header --> - CSS: /* #region kpi-cards */…/* #endregion kpi-cards */ - JS: // #region chart-init … // #endregion chart-init - Tag key elements with data-sm attributes: data-sm="kpi-spend", data-sm="filter-date" Each anchor must be unique in the code. Best practices: - Add a loading indicator (spinner or skeleton) while data is being fetched. - When it makes sense, add selectors (dropdowns, date pickers, toggles) that let viewers change query parameters such as date range, account, or metric. - Date controls: offer a genuinely flexible date range, not just a few fixed presets. smQuery's date_range_type accepts today, yesterday, this_month(_inc), last_month, this_year_inc, last_year(_inc), and the last_x_days / last_x_weeks_sun_sat / last_x_weeks_mon_sun / last_x_months / last_x_years families — substitute a number for x (e.g. last_90_days, last_3_months) and append _inc to include the current period. There is NO native quarter or year-to-date preset: deliver 'this/last quarter', 'year to date', and any viewer-picked custom range via date_range_type="custom" with start_date/end_date (YYYY-MM-DD) computed in the dashboard's own JS (derive the boundaries from new Date()). Prefer including a fully custom start/end picker alongside the presets. - Period comparison: when comparison is wanted, add ONE dashboard-wide comparison control and feed the SAME compare params into EVERY widget's smQuery — time-series charts too, not only scorecards. compare_type="prev_range" (previous period), "prev_year" (same period last year), "prev_year_weekday", or "custom" (with compare_start_date/compare_end_date, YYYY-MM-DD); compare_show="perc_change" (default), "abs_change", or "value". For a year-over-year time-series overlay, either use compare_type or issue a second smQuery for the prior period and plot it as an additional series. - Give each chart/table/KPI its own stable smQuery key (see the 'code' param) so rapidly changing a selector can't show stale data from a previous selection. - If an 'upload' response includes `code_warnings`, the board will render empty/wrong data or never refresh — fix the issue it names (a static board with no smQuery calls, or column mapping via requested_field_ids) and re-upload before sharing the board.

• Supermetrics Guide

  Explain what Supermetrics can do, what's new, or how to fix a common problem. Use mode="tour" (the default) for what the user can do; mode="whats_new" for recent changes. Not for looking up data sources, accounts or fields. Call tour/whats_new at most once per conversation. TROUBLESHOOTING: when the user reports a common problem, fetch the matching guide and walk them through it before offering a support ticket. Connecting / access: connect_data_source (sign-in / "no accounts found"), google_connectors (GA4/Search Console/YouTube/etc. access), meta_instagram (Facebook/Instagram setup), microsoft_connectors (Microsoft Ads/Bing Webmaster), linkedin_connectors (Ads vs Company Pages), tiktok_connectors (Ads vs Organic), amazon_connectors (Ads/DSP/Seller/Vendor), data_warehouse (BigQuery/Snowflake), reconnect (expired connection). Licensing and accounts: license_and_trials (LICENSE_NOT_FOUND / trial expired), data_source_on_plan (LICENSE_DATA_SOURCE_NOT_AVAILABLE), destination_on_plan (AI Chats destination missing), prioritized_accounts ("not a prioritised account"), manage_users_and_accounts (adding users/accounts and making a new account usable). Data and queries: no_data (empty results), data_discrepancies (numbers don't match the platform), ga4_data (GA4 sampling/thresholding/partial data), query_errors (date/field/account errors), quotas_and_limits (quota exceeded). Campaigns: write_access. Each returns steps the user can follow without Supermetrics staff.