Google Ads

The Google Ads app connects Google Ads to Sprigr Team. Agents can run GAQL reports across every resource, metric and segment, create, update and remove campaigns, ad groups, ads, criteria, assets, audiences, bidding strategies and conversion actions, plan keywords and reach, review recommendations, upload offline conversions and Customer Match lists, and read billing. A scheduled import lands daily performance reports in month-sharded data indexes with 13 months of history, so ad spend can be joined to Shopify orders by SKU and date, to GA4 by campaign name, and to Merchant Center by offer id.

Note

Google Ads ships as a marketplace app with one connection per install. An admin connects one Google account that has access to your Google Ads accounts, and every agent with the app acts through it. A default customer ID and, if you use a manager account, a login customer ID are set once for the install.

Prerequisites

• A Google account with access to the Google Ads accounts you want agents to work with, directly or through a manager (MCC) account.
• Admin or Owner role in your Sprigr Team organisation to install the app.

Installing and connecting

1. Install the app

   Sign in to team.sprigr.com, open Apps in the sidebar, find Google Ads under Available, and install it. See Installing Apps.

2. Connect a Google account

   Open the app’s settings page from Apps > Installed and click Connect Google Ads. Sign in with a Google account that has Google Ads access and approve the request. The page then shows the accessible customers.

3. Set the default customer

   Choose the Google Ads customer ID that tools use when a request does not name one, under Default Google Ads customer. If your accounts sit under a manager account, also set the Login customer (MCC) so operations on client accounts are authorised correctly. Agents can do both with google_ads_set_default_customer and google_ads_set_login_customer_id.

4. Check the connection

   Ask your agent “Is Google Ads connected, and which accounts can you see?” It calls google_ads_connection_status.

Try asking your agent

“What did we spend on Search campaigns last week, and what was the cost per conversion by campaign?”

“Which search terms drove clicks but no conversions in the last 30 days?”

“Pause the ‘Winter Sale’ campaign.”

Reporting import and data indexes

Every 15 minutes the app walks each import customer one day at a time through seven report grains and upserts them into month-sharded data indexes: campaign daily, ad group by device, keyword, search terms, shopping products by offer id, geo, and conversion actions. The first pass backfills 13 months; after that the trailing three days are re-imported hourly because Google restates conversions. Money is in the customer’s currency.

• google_ads_import_status shows which customers are being walked, the phase (backfill or trailing), cursor date, rows indexed and any errors or quota hits.
• google_ads_set_import_customers pins an allowlist of customer IDs to import; with none set the import covers every enabled client under the login customer, or the default customer.
• google_ads_import_restart discards walk state so the next run reseeds a fresh backfill. Every write is an upsert, so re-importing is safe but spends API quota.

Because the indexes are in your Sprigr workspace, agents can answer questions that join ad spend to orders, sessions and product listings without exporting anything.

What agents can do

The app exposes 125 tools. At a category level:

• Reporting: google_ads_search and google_ads_search_stream run any GAQL query, paged or streamed; google_ads_search_fields and google_ads_get_field describe the field catalogue so queries are valid.
• Universal write: google_ads_mutate creates, updates and removes any mix of resources in one atomic call; google_ads_request reaches any REST endpoint not covered by a named tool.
• Per-resource mutate tools for campaigns, campaign budgets, criteria, assets, asset sets, bid modifiers, labels, shared sets, drafts, groups, conversion goals and customizers; ad groups and their ads, criteria, assets, labels and customizers; ads and ad parameters; assets, asset groups and their signals and listing group filters; bidding strategies, data exclusions and seasonality adjustments; conversion actions, custom variables and value rules; audiences, user lists and Customer Match; remarketing; experiments; and more.
• Planning and insight: keyword planning, reach planning, recommendations.
• Uploads and jobs: offline conversion uploads, Customer Match uploads, batch jobs.
• Account: list accessible customers, connection status, default and login customer, billing.

Writes that change spend or delivery, such as pausing a campaign or editing a budget, are actions the agent takes at your instruction; ask it to describe the change before it runs.

Common use cases

• Weekly performance brief. A scheduled workflow reports spend, conversions and cost per conversion by campaign, with week-over-week change, from the data indexes.
• Search term hygiene. The agent finds wasteful search terms and, at your instruction, adds them as negative keywords.
• Budget pacing. “Are we on track to spend the monthly budget?” compares month-to-date spend with the plan.
• Cross-channel attribution. Ad spend by SKU joined to Shopify orders by SKU and date shows return on ad spend per product.
• Shopping feed problems. Shopping performance by offer id joined to Merchant Center product status surfaces disapproved products that were still spending.

Troubleshooting

Not connected Nobody has completed the Connect Google Ads step, or the connection was revoked. Reconnect from the app’s settings page.

“Customer not found” or permission errors The request needs a customer ID the connected Google account cannot access, or the login customer (MCC) is not set for a client account under a manager. Check google_ads_connection_status and set the default and login customer.

Reports are missing recent days The import runs every 15 minutes within a time budget, and the backfill starts 13 months back, so a new install takes a while to reach today. google_ads_import_status shows the cursor per customer and grain.

Quota errors Google Ads enforces API quota per developer token and account. The import backs off automatically; live queries during a backfill can still hit limits. Narrow queries or wait for the backfill to finish.

Next steps

• Google Analytics: Sessions and conversions to join with ad spend.
• Google Merchant Center: Product listings and performance by offer id.
• Shopify: Orders to attribute spend against.
• Integrations Overview: See all available integrations.