accounts_discovery
ChatGPTDiscover 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).
Overview
Query data, analyze performance & manage ad campaigns across 200+ platforms — no account needed. Share Claude-generated live dashboards. Supports Google Ads, Facebook Ads (Meta), Google Analytics, Instagram, TikTok, YouTube, LinkedIn, Shopify, Google My Business, Amazon Ads, Microsoft Advertising (Bing), Pinterest, Snapchat, Klaviyo, HubSpot, Salesforce. Covers advertising, analytics, social media, CRM, ecommerce & email marketing
Tools
campaign_and_resource_get
ChatGPTGet campaign details or list campaigns and related resources. resource_type determines what to query (pass options in params): - campaigns (default): list or get single campaign. params: {status, campaign_id, campaign_detail_level} - health_check: performance snapshot (spend, clicks, conversions, ctr, cpc, cpa, roas). params: {campaign_id} - forecast: estimate performance at different spend levels (AW/FA). params: {bids, targeting, optimization_goal} - assets: list assets. Use id as asset_id in creatives - pages: Facebook Pages (FA). posts: promotable Page posts (FA). params: {page_id} - keyword_ideas/keyword_volumes (AW/AC). params: {keywords, url, language, location} - targeting_search: search targeting catalog. params: {query, type} - reach_estimate: audience size estimate. params: {targeting} - audiences, recommendations, history, conversions: params: {campaign_id} where applicable Response: {results: [...], notes: [...]}
campaign_create
ChatGPTCreate a campaign on Google Ads, Facebook Ads, TikTok Ads, LinkedIn Ads, Microsoft Ads, or ChatGPT Ads. Response: {results: [campaign], notes: [strings]}. Partial success: if campaign creates but ad group/ad fails, returns campaign_id + notes.
campaign_update
ChatGPTUpdate an existing campaign. Only provided fields are changed. Response: {results: [campaign], notes: [strings]}. Notes explain ignored fields, platform limitations, and unchanged entities. Response ads include review status (APPROVED, APPROVED_LIMITED, DISAPPROVED, IN_REVIEW). Unchanged ad groups/ads are shown as summaries only (no IDs or details). To get full campaign details after updating, use campaign_and_resource_get with the campaign_id.
contact_supermetrics
ChatGPTSend feedback, create a support ticket, or submit a sales enquiry. Only create support tickets when explicitly authorized by the user.
creative_picker
ChatGPTOpen the creative picker to browse, upload, AI-generate, or import ad creatives with visual preview. Works with both image and video creatives. Use it whenever the user wants to add an image or video. Pass asset_url or asset_prompt in params to auto-start; if the user already has an asset URL or ID, pass it directly to manage_campaign instead.
data_query
ChatGPTQuery data from Google Ads, Facebook Ads, Google Analytics, LinkedIn Ads, TikTok Ads, Microsoft Ads, Shopify, HubSpot, and 200+ other platforms. Use discovery tools first: data_source_discovery for config, accounts_discovery for account IDs, field_discovery for fields. Returns schedule_id — pass to get_async_query_results immediately.
data_source_discovery
ChatGPTDiscover 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.
field_discovery
ChatGPTDiscover 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_async_query_results
ChatGPTRetrieve results from a data_query using its schedule_id. Call immediately after data_query returns. Keep polling until status is 'completed' or failed.
get_today
ChatGPTGet 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
ChatGPTInstagram 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_business_context
ChatGPTStore 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. When a discovery response surfaces a scope only as a tag list (its context was too large to inline), read the tags relevant to the action you're taking with get. Also call get 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. A discovery response also states when the team has no saved context yet, so don't call get merely to check whether any exists. Apply context when analysing data and making changes.manage_campaign
ChatGPTCreate or update a campaign (AW/FA/TIK/LIA/AC/CGPTA/SCM). Provide campaign_id to update an existing campaign; omit it to create a new one (budget_amount required when creating). On update only provided fields change. Also creates/updates ad groups/ads — see ad_groups (operations inferred from id presence). AW PMax: set ad_groups[].id to update asset groups. AW/AC keywords: ad_groups[].add_keywords/remove_keywords append/remove POSITIVE keywords; targeting REPLACES (send full set). Partial success possible: check write_status and failures if present, otherwise notes; don't retry blindly. Creative: use asset_url (public https:// URL), asset_id, upload_ref (from creative_picker), or object_story_id (existing post). Use campaign_and_resource_get for full details after writing.
manage_dashboards
ChatGPTShare 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); c…
manage_user_and_team
ChatGPTManage 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.
marketing_utilities
ChatGPTFree marketing utilities: no Supermetrics subscription or connected data source needed. Actions: - utm_build: tag each of the urls with source/medium/campaign/term/content, correctly encoded (macros like {campaignid} kept), validated against your team's conventions. - utm_parse: audit the urls against your team's conventions and GA4 channel rules. - pagespeed_check: PageSpeed Insights for up to 10 urls (run in parallel; 30s-2min): scores, lab and field vitals, top fixes; detail="full" for every finding. Returns within ~45s; if checks are still running it returns status="running" and a job_id: poll with {"action":"pagespeed_check","job_id":...} about every 30s. Results are cached for 24h (cached=true, checked_at); pass refresh=true only after the page has changed. - link_check: follow up to 50 urls through redirects; do UTM and click-id params (gclid, fbclid...) reach the landing page, and at which hop are they lost. Also broken pages, loops, tagging mistakes. - web_vitals_trend: ~6 months of real-user LCP/INP/CLS/FCP/TTFB for up to 50 sites (bare domain) or pages. - safety_check: up to 50 urls and every host they redirect through: Web Risk malware/phishing flags, invalid or expiring certificates, domains expiring soon or registered in the last 30 days. - link_preview: how up to 50 urls render when shared on LinkedIn, Facebook, X and Slack; flags missing or small og:image, missing description, truncated titles. - email_dns: SPF, DKIM, DMARC, MX and BIMI for up to 50 domains (urls may be domains, emails or URLs). - char_limits: exact lengths of up to 200 texts against Google Ads, Meta, LinkedIn and X limits (counted as each platform counts). Use it whenever copy must fit a limit; do not count characters yourself. Google asset fields (path, long_headline, business_name, callout, sitelink_text, sitelink_description) are checked only when named in field. Results: every result has input (as sent), url, status (ok|warning|critical|unknown) and findings[] of {code, severity, message, suggestion?, ...extras}; unknown results carry error {code, message} (e.g. quota_exhausted, daily_limit, no_data, url_throttled). Each batch has a summary of counts. UTM conventions come from business context (tags='utm-conventions'). A JSON object is enforced; every key is optional; lists are exact, case-sensitive matches: {"approved_sources":[...],"approved_mediums":[...],"blocklist":{"utm_campaign":["test"]}, "regex":{"utm_campaign":"\d{4}"},"max_length":{"utm_campaign":60},"casing":"lowercase"|"as_is", "separator":"-"|"_","require_all_core":true} When utm_source is a known ad network (google, bing, facebook/instagram, tiktok, linkedin, snapchat, pinterest), utm_build returns network {medium, campaign_macro, id_macro, click_id} and both actions flag macros written in another network's syntax, which that network would leave unfilled. utm results report conventions_source: team (JSON enforced), team_free_text (returned as team_conventions for you to apply) or defaults (lowercase, hyphens).
resources_manage
ChatGPTOpen the media picker UI for browsing and selecting ad creatives. Skip if you already have asset_id, upload_ref, or asset_url.
supermetrics_guide
ChatGPTExplain 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), x_twitter_connectors (X Ads vs X 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), cancel_trial (cancel a trial / "will I be charged?"), 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.
user_info
ChatGPTGet user profile, team info, permissions, and license details.
