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

# Google Sheets add-on

> Pull Meta, Google Ads, TikTok, Snapchat, GA4 and 9 more sources into Google Sheets with the Whathead add-on: query builder, comparisons and scheduled refresh.

The Whathead add-on for Google Sheets pulls ad, analytics and attribution data into your spreadsheets. You build a query in the sidebar (source, accounts, dates, metrics, dimensions and filters), Whathead writes the results at the cell you choose, and you can refresh by hand or on a schedule that runs on Whathead's servers. It works with 14 sources and any Whathead plan with an active trial or subscription.

## Key facts

| | Google Sheets add-on |
| - | - |
| Sources | 14: Meta, Google Ads, TikTok, Snapchat, LinkedIn (beta), X (beta), Reddit (beta), DV360 (beta), Microsoft Advertising, Apple Ads, Amazon Ads, GA4, Adjust, AppsFlyer |
| Price | Free to install. Running queries needs a Whathead account with an active trial or subscription |
| Sign-in | **Sign in with Whathead** in the sidebar, confirmed in a browser tab |
| Queries per spreadsheet | Many, each anchored at a cell |
| Scheduled refresh | Hourly, daily, weekly or monthly; up to 5 schedules per spreadsheet |
| Rows per query | 5 to 1,000,000 (default 10,000) |
| Google permissions | 3: this spreadsheet only, sidebar UI, and calls to Whathead |
| Availability | Google Workspace Marketplace listing pending. Check the [add-on page](https://www.whathead.com/connectors/google-sheets) for the install link |

## Before you start

* Connect the ad platforms and data sources you want to report on in Whathead (**Integrations**). The add-on can only read accounts your workspace has connected.
* Your workspace needs an active trial or subscription. Without one, queries return a subscription-required error.

## Install and sign in

**1. Install the add-on**

Open the [Whathead Google Sheets page](https://www.whathead.com/connectors/google-sheets) and follow the install link, or search for **Whathead** on the Google Workspace Marketplace.

**2. Open the sidebar**

In a spreadsheet, open **Extensions**, choose the Whathead add-on, then **Launch sidebar**.

**3. Sign in with Whathead**

Click **Sign in with Whathead**. A browser tab opens to confirm the sign-in with your Whathead account. The sidebar then connects automatically.

The sidebar session lasts 12 hours. The session token is stored in your browser's local storage for that spreadsheet.

## Build a query

The sidebar walks through these sections:

| Section | What you set |
| - | - |
| Data source | One of the 14 sources |
| Accounts | One or more connected accounts (up to 100 for Meta, Google Ads, LinkedIn and Microsoft Advertising; 50 for most others; 20 for AppsFlyer) |
| Report configuration | Source-specific settings, such as report type |
| Dates | A preset (for example last 7 days, last month) or a custom range |
| Metrics | Up to 100 |
| Split by dimensions | Up to 10 row dimensions and up to 2 column (pivot) dimensions |
| Filters | Up to 50 filters |
| Options | Show blanks as zero, keep previous results on error, combine with old data, add totals, hide headers, add a date note |

You can also add a **comparison period**: previous period, same period last year (optionally matching weekdays) or a custom range, shown as % change, absolute change or the comparison value.

Ratios such as CTR, CPC, CPM and ROAS are recalculated from their parts, so totals and grouped rows are correct rather than averaged.

Queries are saved inside the spreadsheet, in a hidden tab, so they stay with the file.

## Refresh

From the **Extensions** menu you can **Refresh all**, **Refresh queries in this sheet**, **Manage queries** or **Schedule refresh & emailing**.

### Scheduled refresh

* **Frequency:** every 1, 2, 3, 4, 6, 8 or 12 hours; daily; weekly on the weekdays you choose; or monthly on a day from 1 to 28 or the last day of the month.
* **Limit:** up to 5 schedules per spreadsheet.
* **Where it runs:** on Whathead's servers, so the spreadsheet doesn't need to be open.
* **One-time setup:** the first time you schedule a refresh, Whathead asks you to connect Google Sheets in Whathead so its servers can write to the file.
* **Emails:** you can add up to 20 extra recipients. Emails are sent when a scheduled refresh fails or partly fails, not as report deliveries.
* **Auto-pause:** a schedule is switched off after 5 failed runs in a row.

## Limits

| Limit | Value |
| - | - |
| Accounts per query | Up to 200, capped per source (see above) |
| Metrics per query | 100 |
| Row dimensions | 10 |
| Column (pivot) dimensions | 2, with 3 to 500 pivot columns |
| Filters | 50 |
| Rows per query | 5 to 1,000,000 (default 10,000) |
| Queries running at once | 4 per workspace |
| Spreadsheet size | Google's 10 million cell limit applies |
| Cached results | Run results are kept for up to 7 days |

## Related

> [card] [Looker Studio connector](https://docs.whathead.com/reporting/looker-studio-connector.md)
>
> The same sources in Looker Studio dashboards.

> [card] [Platform capability matrix](https://docs.whathead.com/platforms/capability-matrix.md)
>
> Which platforms are reporting sources.

> [card] [Pricing & limits](https://docs.whathead.com/pricing-and-limits.md)
>
> Plans and trial details.

> [card] [Ad reporting with Claude & ChatGPT](https://docs.whathead.com/ai-assistant/reading-and-reports.md)
>
> Ask your AI assistant for reports instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.