> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Google Ads to Vortex IQ

> Connect Google Ads to Vortex IQ for 75 KPI cards including Cross-Platform Metrics cards for revenue at risk, ads on out-of-stock SKUs, and Google Ads revenue share.

Connecting Google Ads to Vortex IQ gives the AI OS a live read on every campaign, ad group, and keyword in your account. Nerve Centre populates with 75 KPI cards covering campaign performance, budget monitoring, keyword intelligence, geographic performance, alert detection, and Cross-Platform Metrics signals that only become visible when Google Ads data is paired with your commerce platform and other connectors.

## What data Vortex IQ reads from Google Ads

Vortex IQ connects to the Google Ads API (GAQL) and ingests the following data:

<AccordionGroup>
  <Accordion title="Campaign performance">
    * Spend, impressions, clicks, and conversions at account, campaign, ad group, and keyword level
    * Conversion value (`conversions_value`) for revenue attribution
    * Cost per click (CPC), cost per acquisition (CPA), and ROAS
    * Click-through rate (CTR) and conversion rate
    * Campaign type, status, and bidding strategy
    * Budget utilisation per campaign
  </Accordion>

  <Accordion title="Keywords and search terms">
    * Keyword performance including Quality Score
    * Search terms report (actual queries that triggered ads)
    * Wasted spend on zero-conversion search terms
    * Top keywords by spend and by conversions
  </Accordion>

  <Accordion title="Geography and device">
    * Conversions, spend, and ROAS by country and city
    * Performance breakdown by device (desktop, mobile, tablet)
    * Impression share by geography
  </Accordion>

  <Accordion title="Day and time performance">
    * Spend, ROAS, and conversion rate by hour of day
    * Spend and conversions by day of week
    * Conversion lag (time from click to conversion)
  </Accordion>

  <Accordion title="Landing page performance">
    * CPC, conversion rate, and revenue attributed per landing page URL
  </Accordion>
</AccordionGroup>

<Note>
  Vortex IQ uses the Google Ads API with GAQL (Google Ads Query Language). The connector requires a Google Ads account with at least one active campaign. For MCC (Manager Account) setups, you connect at the MCC level and Vortex IQ surfaces per-child-account alerts individually.
</Note>

## How to connect

<Steps>
  <Step title="Open Connected Sources">
    In your Vortex IQ workspace, go to **Settings → Connected Sources**. You need Admin role in the workspace to connect sources.
  </Step>

  <Step title="Find the Google Ads card">
    Locate the Google Ads connector card and click **+ Connect**. The connector drawer opens showing the scopes Vortex IQ will request.
  </Step>

  <Step title="Authenticate with Google">
    Click **Connect with Google**. A new tab opens at Google's authorisation screen. Sign in with the Google account that has access to your Google Ads account. Review the requested scope and click **Allow**.
  </Step>

  <Step title="Select your account or MCC">
    After authentication, Vortex IQ shows a list of Google Ads accounts accessible under your login. Select the account or MCC you want to connect.
  </Step>

  <Step title="Wait for the first data pull">
    Google Ads KPI cards appear in Nerve Centre within 5 to 15 minutes for active campaigns. Historical data backfills progressively.
  </Step>
</Steps>

<Note>
  The scope Vortex IQ requests is `https://www.googleapis.com/auth/adwords` (read-only access to Google Ads data). No campaign changes, bid adjustments, or budget modifications are made by Vortex IQ.
</Note>

## Available KPI cards

Google Ads is the most instrumented ad platform in Vortex IQ with 75 Nerve Centre cards, including a unique set of Cross-Platform Metrics cards.

<CardGroup cols={2}>
  <Card title="Executive overview" icon="gauge">
    **ROAS** - Return on ad spend (`conversions_value ÷ cost`). Key Metrics gauge card. The account-level efficiency number. Alerts at configurable thresholds.

    **Total Spend** - Account-level spend in the period.

    **ROAS by Campaign** - Per-campaign ROAS breakdown. Key Metrics bar chart for identifying which campaigns are carrying vs dragging the account.

    **Wasted Spend** - Spend on zero-conversion keywords and search terms.

    **Zero-Conversion Spend** - Spend where no conversion occurred in the period. Key Metrics alert card.
  </Card>

  <Card title="Alert cards" icon="bell">
    **ROAS Drop Alert** - Fires when ROAS drops more than 25% vs the prior 7-day same-day-of-week baseline. The first alert when the ad team's day is going to be difficult. Suppressed before 14:00 local to avoid incomplete-data false positives.

    **Conversion-Tracking-Broken Alert** - Fires when the click-to-conversion ratio collapses in a way that indicates a pixel or tag break rather than real performance. Key Metrics alert card.

    **CPC Spike Alert** - Fires when CPC rises sharply above the same-DOW baseline.

    **Disapproved-Ad Burst Alert** - Fires when a cluster of ads receive disapprovals in a short window.

    **Wasted-Spend Burst Alert** - Fires when spend on zero-conversion terms rises sharply.

    **Conversion Drop Alert** - Fires when conversion volume drops sharply. Key Metrics alert card.
  </Card>

  <Card title="Campaign performance" icon="megaphone">
    **Campaign Comparison** - Side-by-side table of spend, ROAS, CPC, CTR, and conversion rate per campaign.

    **Top Performing Campaigns** - Highest-ROAS campaigns in the period.

    **Worst Performing Campaigns** - Lowest-ROAS campaigns - pause or restructure candidates.

    **Overspending Campaigns** - Campaigns pacing above daily budget.

    **Underspending Campaigns** - Campaigns restricted by budget before end of day.

    **Budget Utilisation** - Spend vs budget gauge per campaign.
  </Card>

  <Card title="Keyword intelligence" icon="search">
    **Wasted Spend** - Spend on keywords that generated zero conversions.

    **Quality Score Distribution** - Distribution of keyword Quality Scores across the account.

    **Top Keywords by Conversions** - Highest-converting keywords.

    **Top Keywords by Spend** - Highest-spend keywords.

    **Search Terms Report** - Actual queries triggering your ads, with spend and conversion data.

    **CPA by Keyword** - Cost per acquisition broken out per keyword.
  </Card>

  <Card title="Geography and device" icon="globe">
    **Conversions by Country** - Choropleth map of conversion volume by country.

    **Spend by Country** - Choropleth map of spend by country.

    **Top Cities by Conversions** - Highest-converting cities.

    **CTR by Region** - Click-through rate by geographic region.

    **ROAS by Region** - ROAS breakdown by region.

    **Conversions by Device** - Desktop vs mobile vs tablet conversion split (donut chart).

    **ROAS by Device** - ROAS per device type.
  </Card>

  <Card title="Day and time" icon="clock">
    **ROAS by Day of Week** - Best and worst days for return on ad spend.

    **Spend by Hour** - Intra-day spend distribution.

    **Conversions by Hour** - Heatmap of conversion volume by hour of day.

    **CPC by Hour** - CPC variation across hours for dayparting optimisation.

    **Conversion Lag** - Distribution of time from click to conversion.
  </Card>
</CardGroup>

### Cross-Platform Metrics cards

Google Ads unlocks a set of Cross-Platform Metrics cards when paired with a commerce platform connector (Shopify, BigCommerce, or Adobe Commerce) and monitoring tools:

| Card                                  | Metrics type           | What it shows                                                                                                                                |
| ------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Active Ads on Out-of-Stock SKUs       | Cross-Platform Metrics | Google Ads spend on product URLs where inventory is at zero - the exact keywords and campaigns wasting budget on unsellable products         |
| Revenue at Risk from active incidents | Cross-Platform Metrics | Live revenue-per-minute estimate while a monitoring incident (Datadog, New Relic) is open, attributed to the Google Ads traffic stream       |
| Google Ads Revenue Share              | Cross-Platform Metrics | Google Ads-attributed revenue as a share of total commerce-platform revenue - the paid-search contribution to the business                   |
| Audience Overlap with Email Programme | Cross-Platform Metrics | Overlap between Google Ads audiences and your email list - identifies where paid and owned media are duplicating                             |
| Landing-Page LCP vs Conversion        | Cross-Platform Metrics | Correlation between landing page Largest Contentful Paint score and conversion rate - surface pages where performance is costing conversions |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Google authentication succeeds but no accounts are listed">
    The Google account you authenticated with does not have access to any Google Ads accounts. Sign in to Google Ads directly to confirm which accounts are accessible under that login. If you use an MCC (Manager Account), ensure you signed in with the MCC owner login or a user with account access granted at the MCC level.
  </Accordion>

  <Accordion title="ROAS Drop Alert fires every Monday morning">
    Monday-after-a-promotion is a known false-positive pattern. The alert compares Monday-to-Monday, but if the prior Monday had a sale running and this Monday does not, the baseline is inflated. Document your promotional calendar and treat Monday alerts following a weekend sale as expected. You can raise the alert threshold from 25% to 35% in your workspace alert settings for high-volatility accounts.
  </Accordion>

  <Accordion title="Conversion-Tracking-Broken Alert fired - what do I do first?">
    Open the **Clicks vs Conversions** card. If clicks held normal volume but conversions dropped sharply, the cause is almost always a pixel or tag break. Run a test order on your store and use Google Tag Assistant to check whether the conversion tag fires on the order confirmation page. If the tag does not fire, your conversion tracking has been broken - likely by a recent change to the checkout page. Fix the tag and do not pause campaigns based on this alert alone.
  </Accordion>

  <Accordion title="Google Ads spend differs from what is in the Google Ads UI">
    Vortex IQ reads spend via the Google Ads API, which may have a 1 to 4 hour ingest lag relative to the Google Ads UI. For today's figures, expect a small lag. For prior days (yesterday and earlier), figures should match the UI to within sub-percent rounding differences from currency handling.
  </Accordion>

  <Accordion title="Cross-Platform Metrics cards are empty even with Shopify connected">
    Cross-Platform Metrics cards require both Google Ads and your commerce platform to be connected and synced. If either connector is still in its first-pull window (up to 4 hours for Shopify), the cross-platform join cannot run. Wait for both connectors to show a Connected and synced state, then refresh the Nerve Centre dashboard.
  </Accordion>
</AccordionGroup>