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

# Install the Scrunch Data Studio Connector (v2)

> Install and configure the Scrunch Data Studio v2 connector to compare up to 30 brands side by side in Looker Studio and pull in agent traffic data.

# Data Studio Connector (v2)

The v2 connector is built for agencies and multi-brand organizations. Connect all your brands to a single Looker Studio data source, compare visibility side by side, and optionally pull in agent traffic data — all without juggling separate connectors per brand.

> [!NOTE]
>
> **Connector last updated:** September 14, 2026 — this release adds citation, share-of-voice, site map, and signals fields, and renames the presence metrics to Mention Rate.
>
> Already using the connector? [Here's how to pick up the new fields](#keeping-your-connector-up-to-date) — your existing dashboards keep working exactly as they are.

![Screenshot 2026 05 16 At 11 57 54 AM](https://mintcdn.com/scrunchai/P4hZCw1FPBZknszy/images/Screenshot-2026-05-16-at-11.57.54-AM.png?fit=max\&auto=format\&n=P4hZCw1FPBZknszy\&q=85\&s=06db244662cd09c9786be8305f9a1daf)

**What's new in v2:**

* **Multi-brand support** — connect 1 to 30+ brands in a single data source
* **Agent Traffic data** — see which AI bots are crawling your site, how often, and where
* **Comparison fields** — brand vs. competitor presence in a single chart
* **Smarter caching and parallel fetching** — faster dashboards, even at scale

> [!NOTE]
>
> Looking for the original single-brand connector? See the [v1 Looker Studio guide](https://developers.scrunch.com/integrations/looker-studio.md).

# Install the Scrunch Data Connector

The connector is not yet in the public gallery. Install it directly using the link below:

> [card] [Install Connector](https://datastudio.google.com/datasources/create?connectorId=AKfycbyi7ba5UXYeYqau1m6upcPFRBm2n0z49C5fg3dSwdbdFArz2IjLbCBc05HcNsoMpLFOcQ)
>
> Open the Scrunch Data Studio Connector

## Configure Your Connection

When you open the connector, you'll see a configuration screen with the following fields:

**1. Enter your API key**

Paste your Scrunch API key. You can provision one from:

**Scrunch** → **Organization** → **Settings** → **API Keys**

> [!WARNING]
>
> When Data Studio shows the parameter checkboxes, **do not** check **"Allow 'API Key' to be modified in reports."** This prevents your key from being exposed to report viewers.
>
> It is safe to check the override boxes for the other parameters:
>
> * Allow "Brand IDs" to be modified in reports
> * Allow "Site ID (optional)" to be modified in reports
> * Allow "Path Filter (optional)" to be modified in reports
>
> These let report viewers customize which brands and data slices they see without exposing your API key.

**2. Enter your Brand IDs**

Enter one or more brand IDs, separated by commas. For example: `46,47,48`

To find a brand ID, open the brand in Scrunch and look at the URL:

`https://app.scrunchai.com/org/.../b/1234/dashboard`

Here, `1234` is your Brand ID.

> [!TIP]
>
> For agency dashboards, enter all client brand IDs here. The connector fetches them in parallel and labels each row with the brand name automatically.

**3. (Optional) Enter a Site ID for Agent Traffic**

If you want agent traffic data (which AI bots are crawling your site), enter your Site ID.

Leave this blank if you only need AI visibility metrics (presence, position, sentiment).

> [!NOTE]
>
> You can find your Site ID in **Scrunch** → **Brand** → **Agent Traffic**. The Site ID can be quickly found in the URL → [https://app.scrunchai.com/org/](https://app.scrunchai.com/org/) ... /sites/**\{site\_id}**\
> \
> *If you haven't set up Agent Traffic yet, skip this for now.*

**4. (Optional) Set a Path Filter**

Restrict agent traffic results to a specific URL path prefix (e.g., `/blog` to only see bot traffic to your blog). Leave blank to include all paths.

> [!TIP]
>
> Path Filter is your friend on high-traffic sites — narrowing a chart to one section (like `/blog/`) makes the Agent Traffic API respond much faster and helps with the timeout errors covered in the [troubleshooting guide](https://developers.scrunch.com/integrations/data-studio-troubleshooting.md).

> [!NOTE]
>
> Time bucketing is automatic — the connector picks daily or weekly aggregation based on whichever date dimension you put on the chart (`Date` for daily, `Date Week` for weekly). You don't need to configure it.

**5. Connect**

Click **Connect** in the top right. Data Studio will load the schema and you're ready to build.

## Keeping your connector up to date

We ship connector updates — new fields, new data sources, fixes — and you never need to reinstall the connector or rebuild a data source to get them.

Looker Studio does not detect schema changes on its own, though. Your data source keeps the field list it had when it was created, so newly added fields stay hidden until you refresh it.

> [!NOTE]
>
> **Your existing dashboards stay working.** Connector updates are additive by design: we do not remove fields, change a field's ID, or change its type or aggregation — those are the changes that break a Looker Studio chart. Every chart you have already built keeps rendering exactly as it does today. Refreshing only adds new fields to the list you can choose from.

**1. Open a dashboard that uses the connector**

Click **Resource** in the top menu.

**2. Open your data sources**

Click **Manage added data sources**.

**3. Edit the Scrunch data source**

Click **EDIT** next to your Scrunch connector.

**4. Choose what you need**

> [tab] Just get the new fields
>
> 1. Click **REFRESH FIELDS**.
> 2. Review the confirmation of what changed, and apply it.
> 3. Select **Done**.

> [tab] Also change your configuration
>
> Use this when you want to change your API key, which brands you pull, your Site ID, or the Path Filter.
>
> 1. Click **Edit Connection**.
> 2. Make your changes.
> 3. Click **Reconnect**.
> 4. Review the confirmation of what changed.
> 5. Select **Done**.

> [!TIP]
>
> Refreshing one data source does not affect any others. If you keep a separate data source per client or per brand, repeat these steps for each one you want on the latest fields.

## Available Fields

The connector exposes **112 fields** across four Scrunch data sources. Data Studio routes each chart to the right API automatically, based on the fields you pick.

> [!WARNING]
>
> Fields from different sources cannot share a chart — AI visibility, agent traffic, site map, and signals are measured at different grains. Build a separate chart for each. The connector explains this inside the chart if you mix them by accident.

> [tab] AI Visibility
>
> Presence, sentiment, position, and citations from AI responses. This is the source a chart uses unless it names a field from one of the other three.
>
> > [accordion] Brand & date (7)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Brand ID | `brand_id` | NUMBER | |
> > | Brand Name | `brand_name` | TEXT | |
> > | Date | `date` | YEAR\_MONTH\_DAY | |
> > | Date Week | `date_week` | YEAR\_WEEK | |
> > | Date Month | `date_month` | YEAR\_MONTH | |
> > | Date Quarter | `date_quarter` | YEAR\_QUARTER | |
> > | Date Year | `date_year` | YEAR | |
>
> > [accordion] Prompts & audience (9)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Prompt | `prompt` | TEXT | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> > | Prompt ID | `prompt_id` | NUMBER | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> > | Tag | `tag` | TEXT | |
> > | Prompt Topic | `prompt_topic` | TEXT | |
> > | Stage | `stage` | TEXT | |
> > | Branded | `branded` | BOOLEAN | |
> > | Country | `country` | TEXT | |
> > | Persona Name | `persona_name` | TEXT | |
> > | Persona ID | `persona_id` | NUMBER | |
>
> > [accordion] AI platform (2)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | AI Platform | `ai_platform` | TEXT | |
> > | AI Platform Search Enabled | `ai_platform_search_enabled` | BOOLEAN | |
>
> > [accordion] Competitors (3)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Competitor Name | `competitor_name` | TEXT | |
> > | Competitor ID | `competitor_id` | NUMBER | |
> > | Cited Competitor | `cited_competitor_name` | TEXT | The competitor that owns a cited source. Use this instead of Competitor Name when the chart has citation metrics in it — Competitor Name is calculated on a path that cannot produce citation metrics. |
>
> > [accordion] Cited sources (7)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Source URL | `source_url` | URL | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> > | Citation Domain | `domain` | TEXT | Registered domain of a cited source (e.g. example.com). |
> > | Citation Owner | `owner` | TEXT | Who owns the cited domain: brand, competitor or other. |
> > | Source Topic | `source_topic` | TEXT | Topic assigned to a cited source's domain. Only works alongside a citation metric. |
> > | Citation Segment | `citation_segment` | TEXT | Citation segment the cited source falls into. Only works alongside a citation metric. |
> > | Source Type | `source_type` | TEXT | Ownership class of the cited source: brand, competitor or other. Compare with 'Citation Owner', which is the same idea on the citation-metric path. |
> > | Source Domain (legacy) | `source_domain` | TEXT | Host of a cited source, www-stripped. Cannot be combined with citation metrics — use Citation Domain instead when charting citations. |
>
> > [accordion] Where & how you appear (3)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Position Bucket | `position_bucket` | TEXT | Where your brand appears inside a response: top, middle or bottom. Responses that don't mention your brand are excluded from this breakdown. |
> > | Sentiment Band | `sentiment_band` | TEXT | How your brand is talked about when mentioned: positive, mixed or negative. Responses that don't mention your brand are excluded from this breakdown. |
> > | Mention Rank | `rank` | NUMBER | In the product this is 'Mention Rank'. First-occurrence rank of the entity inside a response (1 = mentioned first). |
>
> > [accordion] Core metrics (12)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Responses | `responses` | NUMBER | Additive, so totals are safe. |
> > | Unique Prompts | `unique_prompts` | NUMBER | Prompt variants that produced responses. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
> > | Mention Rate | `mention_rate` | PERCENT | The share of AI responses whose text mentions your brand by name. This is the current name for what used to be called Brand Presence (%) — same data, same numbers. |
> > | Brand Presence (%) (legacy) | `brand_presence_percentage` | PERCENT | **Legacy** — use `Mention Rate`. Same numbers; kept so existing charts keep working. |
> > | Positioning Score | `positioning_score` | NUMBER | How prominently your brand appears inside the responses that mention it, 0-100 (top=100, middle=50, bottom=0). This is the current name for what used to be called Brand Position — same data, same numbers. |
> > | Brand Position (legacy) | `brand_position_score` | NUMBER | **Legacy** — use `Positioning Score`. Same numbers; kept so existing charts keep working. |
> > | Sentiment Score | `sentiment_score` | NUMBER | How your brand is talked about in the responses that mention it, 0-100 (positive=100, mixed=50, negative=0). This is the current name for what used to be called Brand Sentiment — same data, same numbers. |
> > | Brand Sentiment (legacy) | `brand_sentiment_score` | NUMBER | **Legacy** — use `Sentiment Score`. Same numbers; kept so existing charts keep working. |
> > | Brand Mention Share of Voice (%) | `brand_share_of_voice` | PERCENT | In the product this is 'Mention Share of Voice'. Slices sum to 1 across the tracked set. |
> > | Brand Mention Rank | `brand_avg_rank` | NUMBER | In the product this is 'Mention Rank'. Average first-occurrence rank of your brand. |
> > | Brand Unique Prompts | `brand_unique_prompts` | NUMBER | Prompt variants where your brand was mentioned. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
> > | Brand Unique Responses | `brand_unique_responses` | NUMBER | Responses that mentioned your brand. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
>
> > [accordion] Competitor metrics (6)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Competitor Mention Rate | `competitor_mention_rate` | PERCENT | The share of AI responses whose text mentions the competitor by name. Current name for what used to be called Competitor Presence (%) — same data. |
> > | Competitor Presence (%) (legacy) | `competitor_presence_percentage` | PERCENT | **Legacy** — use `Competitor Mention Rate`. Same numbers; kept so existing charts keep working. |
> > | Competitor Mention Share of Voice (%) | `competitor_share_of_voice` | PERCENT | In the product this is 'Mention Share of Voice'. Slices sum to 1 across the tracked set. |
> > | Competitor Mention Rank | `competitor_avg_rank` | NUMBER | In the product this is 'Mention Rank'. Average first-occurrence rank of the competitor. |
> > | Competitor Unique Prompts | `competitor_unique_prompts` | NUMBER | Prompt variants where the competitor was mentioned. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
> > | Competitor Unique Responses | `competitor_unique_responses` | NUMBER | Responses that mentioned the competitor. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
>
> > [accordion] Citation metrics (18)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Citation Rate (%) | `citation_rate` | PERCENT | Share of responses that include at least one citation, whoever owns it. A rate on a 0-1 scale. |
> > | Brand Citation Rate (%) | `brand_citation_rate` | PERCENT | Share of responses that cite at least one brand-owned domain. A rate on a 0-1 scale. |
> > | Competitor Citation Rate (%) | `competitor_citation_rate` | PERCENT | Share of responses that cite at least one competitor-owned domain. Cannot be broken down by Competitor Name or Competitor ID. |
> > | Brand Citation Share of Voice (%) | `brand_citation_share_of_voice` | PERCENT | Of responses that cite anything, the share citing a brand-owned domain. A rate on a 0-1 scale. |
> > | Competitor Citation Share of Voice (%) | `competitor_citation_share_of_voice` | PERCENT | Of responses that cite anything, the share citing a competitor-owned domain. Cannot be broken down by Competitor Name or Competitor ID. |
> > | Citation Count | `citation_count` | NUMBER | Total citation occurrences. A response citing three URLs counts three. |
> > | Brand Citation Count | `brand_citation_count` | NUMBER | Citation occurrences resolving to a brand-owned domain. Additive, so totals are safe. |
> > | Competitor Citation Count | `competitor_citation_count` | NUMBER | Citation occurrences resolving to a competitor-owned domain. Cannot be broken down by Competitor Name or Competitor ID. |
> > | Citation Unique Responses | `citation_unique_responses` | NUMBER | Responses containing at least one citation. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
> > | Brand Citation Unique Responses | `brand_citation_unique_responses` | NUMBER | Responses citing at least one brand-owned domain. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
> > | Competitor Citation Unique Responses | `competitor_citation_unique_responses` | NUMBER | Responses citing at least one competitor-owned domain. Cannot be broken down by Competitor Name or Competitor ID. |
> > | Citation Unique Domains | `citation_unique_domains` | NUMBER | Distinct citation hosts. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
> > | Citation Unique Response-Domains | `citation_unique_response_domains` | NUMBER | This is the grain the product's Citations page composes on, so an Owner or Citation Domain breakdown reconciles with that page exactly. Distinct response/domain pairs — this is what the Citations dashboard donut shows. |
> > | Brand Citation Unique Domains | `brand_citation_unique_domains` | NUMBER | Distinct brand-owned citation hosts. Distinct count, so a total across rows double-counts anything appearing in more than one row. |
> > | Competitor Citation Unique Domains | `competitor_citation_unique_domains` | NUMBER | Distinct competitor-owned citation hosts. Cannot be broken down by Competitor Name or Competitor ID. |
> > | Brand Citation Mention Rate (%) | `brand_citation_mention_rate` | PERCENT | Share of cited pages that name your brand in the page content itself. A rate on a 0-1 scale. |
> > | Competitor Citation Mention Rate (%) | `competitor_citation_mention_rate` | PERCENT | Share of cited pages that name a competitor in the page content itself. A rate on a 0-1 scale. |
> > | Influence Score | `weighted_index` | NUMBER | Per-source ranking metric combining citation frequency with reach. Requires a Citation Domain or Source URL breakdown in the same chart. |
>
> > [accordion] Brand vs. competitor comparison (4)
> >
> > | Field | ID | Type | Notes |
> > | - | - | - | - |
> > | Entity Name | `entity_name` | TEXT | Brand or competitor name. Use as breakdown to compare presence side by side. |
> > | Entity Type | `entity_type` | TEXT | 'Brand' or 'Competitor'. Use to filter or color-code comparison charts. |
> > | Mention Rate (comparison) | `entity_mention_rate` | PERCENT | Unified mention rate for brand-vs-competitor charts. Current name for what used to be called Presence (%) — same data. |
> > | Presence (%) (legacy) | `presence_percentage` | PERCENT | **Legacy** — use `Mention Rate (comparison)`. Same numbers; kept so existing charts keep working. |

> [tab] Agent Traffic
>
> Which AI bots crawl your site, how often, and where. Requires a **Site ID** in the data source configuration.
>
> | Field | ID | Type | Notes |
> | - | - | - | - |
> | Site | `site` | TEXT | |
> | Path | `path` | TEXT | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Agent Source | `agent_source` | TEXT | |
> | Agent Type | `agent_type` | TEXT | |
> | Agent Requests | `agent_requests` | NUMBER | Additive, so totals are safe. |
>
> > [!NOTE]
> >
> > Monthly aggregation is not available for agent traffic. Use `Date Week` for the closest equivalent.

> [tab] Site Map
>
> Your page inventory with AI search readiness scores. This is a current snapshot rather than a time series, so do not put a date dimension on these charts.
>
> | Field | ID | Type | Notes |
> | - | - | - | - |
> | Page URL | `page_url` | URL | A page in your brand's site map. High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Page Title | `page_title` | TEXT | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Page Description | `page_description` | TEXT | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Page Canonical URL | `page_canonical_url` | URL | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Page ID | `page_id` | NUMBER | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Page Depth | `page_depth` | NUMBER | URL path depth. 0 is the site root. |
> | Page Domain | `page_domain` | TEXT | |
> | Page Is Priority | `page_is_priority` | BOOLEAN | |
> | Page Has Optimized Content | `page_has_optimized_content` | BOOLEAN | Whether AXP optimized content is currently live for this page. |
> | Page Audit Score | `page_audit_score` | NUMBER | AI search readiness score for the page, 0-100. An average across the rows in the chart, not a total. |
> | Page Count | `page_count` | NUMBER | Counts pages. Use with Page Depth or Page Is Priority to size sections of the site. |

> [tab] Signals
>
> Detected changes in AI visibility from Scrunch's nightly sweep. One row per detection.
>
> | Field | ID | Type | Notes |
> | - | - | - | - |
> | Signal Date | `signal_date` | YEAR\_MONTH\_DAY | The date the nightly sweep detected this signal for. |
> | Signal Metric | `signal_metric` | TEXT | Which metric moved: presence\_rate, position\_top\_rate or cited\_domain\_rate. |
> | Signal Alert Type | `signal_alert_type` | TEXT | level\_change for a step shift, trend for sustained drift. |
> | Signal Direction | `signal_direction` | TEXT | up, down or none. |
> | Signal Scope | `signal_scope` | TEXT | Slice granularity: account, account\_platform, topic or topic\_platform. |
> | Signal Subject | `signal_subject_kind` | TEXT | Whether the signal is about your brand or a competitor. |
> | Signal Tier | `signal_tier` | TEXT | Confidence tier, e.g. high or provisional. |
> | Signal Platform | `signal_platform` | TEXT | AI platform. Multi-platform signals carry the literal value (multi). |
> | Signal Topic | `signal_topic` | TEXT | Topic labels for the slice, comma-joined when a signal covers several. |
> | Signal Country | `signal_country` | TEXT | |
> | Signal ID | `signal_id` | NUMBER | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Signal Fingerprint | `signal_fingerprint` | TEXT | Stable identity that survives nightly re-detection. Use it to track one issue over time. |
> | Signal: What Happened | `signal_narrative` | TEXT | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Signal: Why It Matters | `signal_why` | TEXT | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Signal: What To Do | `signal_action` | TEXT | High cardinality, so it reads well in a table but poorly as a breakdown, where it produces hundreds of series. |
> | Signal Window Start | `signal_window_start` | YEAR\_MONTH\_DAY | |
> | Signal Window End | `signal_window_end` | YEAR\_MONTH\_DAY | |
> | Signal Baseline | `signal_baseline_definition` | TEXT | |
> | Signal Is Latest Detection | `signal_is_latest` | BOOLEAN | True for the newest detection of each signal fingerprint in the chart's date range. Filter on this to count distinct issues instead of one row per night the issue re-fired. |
> | Signal Count | `signal_count` | NUMBER | Counts signal detections. Signals re-fire nightly, so over a multi-day range the same underlying issue is counted once per night it was detected. |
> | Signal Score | `signal_score` | NUMBER | Engine priority score for the signal. An average across the rows in the chart, not a total. |
> | Signal Current Value | `signal_current_value` | NUMBER | An average across the rows in the chart, not a total. |
> | Signal Baseline Value | `signal_baseline_value` | NUMBER | An average across the rows in the chart, not a total. |
> | Signal Delta | `signal_delta` | NUMBER | Absolute change between the baseline and current windows. An average across the rows in the chart, not a total. |
> | Signal URL Mover Count | `signal_mover_count` | NUMBER | How many individual URLs the signal attributes its change to. Additive, so totals are safe. |
>
> > [!WARNING]
> >
> > Signals re-fire every night they are still detected, so a multi-day range contains the same underlying issue once per night. Filter `Signal Is Latest Detection` to `true` to count distinct issues rather than detections.

## Multi-Brand Dashboards

The v2 connector is designed for comparing brands side by side. Here are some tips:

* **Use `brand_name` as a dimension** to break down any metric by brand
* **Use `brand_id` for filtering** when you want to isolate a specific brand in a chart
* **Comparison fields** (`entity_name`, `entity_type`, `presence_percentage`) work per-brand — each brand's competitors are included automatically

> [!NOTE]
>
> Brand names are automatically resolved from your Scrunch organization. If you see numeric IDs instead of names, make sure your API key has access to the brands you've configured.


## Related topics

- [Troubleshoot the Scrunch Data Studio Connector](https://developers.scrunch.com/integrations/data-studio-troubleshooting.md)
- [Looker Studio Legacy Single-Brand Connector](https://developers.scrunch.com/integrations/looker-studio.md)
- [Data Studio Dashboard Templates for Scrunch](https://developers.scrunch.com/integrations/data-studio-templates.md)


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