# Get Account Status Source: https://developers.scrunch.com/api-reference/account/get-account-status /api-reference/openapi.json get /account Get the subscription state of the account this API key belongs to. Use `status` to tell a trial from a paid or churned account: `trialing` means the account is in its trial, and `current_period_end` is the date that trial ends. `subscription_not_found` means the account has no Stripe subscription on file, which is normal for manually invoiced accounts and is not a sign that the account lapsed. `unknown` means Scrunch cannot vouch for the account's current state, either because its billing record is no longer being kept up to date or because it is in a state this endpoint does not publish yet; keep your current behavior rather than treating it as a lapse. # Account API: Read the Subscription State of an API Key Source: https://developers.scrunch.com/api-reference/account/overview Check whether the account behind a Scrunch API key is on a trial, actively paying, or churned, and read its plan and current billing period. ## Overview The Account API returns the subscription state of the account a Scrunch API key belongs to: the organization, its plan, and the current billing period. Use it to gate a partner experience by trial state, drive an upgrade prompt in your own UI, or confirm the account is still paying before serving premium features. The endpoint is read-only and does not change how the account is billed. *** ## When to use the Account API Use the Account API when you need to: * Tell a trial account from a paid or churned one inside a product-led growth flow * Read the trial end date to schedule reminders or conversion prompts * Confirm the account behind an API key is still active before serving a paid integration For per-brand data such as visibility, prompts, or citations, use the [Query API](/api-reference/query/overview) or [Responses API](/api-reference/responses/overview) instead. *** ## Endpoint | Method | Path | Purpose | | - | - | - | | GET | `/account` | Subscription state of the account this API key belongs to. | The endpoint requires a bearer token with the `query` scope. See [Authentication](/getting-started/authentication). The account is derived from the API key, so there are no path or query parameters. Session (JWT) callers return `400`, because a user may belong to several organizations and the credential alone does not name one. *** ## Example ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/account" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` **Response:** ```json theme={null} { "organization_id": "01M2GBYWVMXJ69VXZ2D5NFJJ6S", "organization_name": "Sitecore PLG Trial", "plan": "enterprise", "plan_display_name": "Enterprise", "status": "trialing", "current_period_start": "2026-09-21T00:00:00Z", "current_period_end": "2027-09-21T00:00:00Z" } ``` *** ## Reading the response ### `status` `status` reports the account's subscription state. Most values mirror Stripe's own subscription statuses: | Value | Meaning | | - | - | | `active` | Paying customer in good standing. | | `trialing` | On a trial. `current_period_end` is the date the trial ends. | | `past_due` | Payment failed but Stripe is still retrying. | | `unpaid` | Stripe stopped retrying after failed payments. | | `paused` | Subscription is paused. | | `incomplete` | Initial payment has not succeeded yet. | | `canceled` | Subscription was canceled. | | `incomplete_expired` | Initial payment window elapsed without success. | Two values are specific to this endpoint: * `subscription_not_found` — Scrunch holds no Stripe subscription record for this account. This is normal for manually invoiced accounts and CS-managed trials, and **is not a sign that the account lapsed**. Treat it as "active unless you know otherwise" in a gating flow. * `unknown` — Scrunch cannot vouch for the account's current state, either because its billing record is no longer being kept up to date or because the subscription is in a state this endpoint does not publish yet. **Keep your current behavior rather than treating it as a lapse.** ### `current_period_end` for trials While `status` is `trialing`, `current_period_end` is the date the trial ends. Use it to schedule reminders or drive an in-product conversion prompt. ### `plan` and `plan_display_name` `plan` is the machine-readable plan name (for example `enterprise`); use it in gating logic. `plan_display_name` is the human-readable label (for example `Enterprise`); show it in UI. Both are empty strings when the account has no plan on file. *** ## Errors | Status | Meaning | | - | - | | `400` | The credential is not scoped to a single account. Returned when the caller authenticates with a user session (JWT) instead of an API key. | | `401` | Missing or invalid bearer token. | | `403` | The API key does not have the `query` scope. | | `404` | The account tied to this API key no longer exists. | # Force Refresh Source: https://developers.scrunch.com/api-reference/agent-pages/force-refresh /api-reference/openapi.json post /{brand_id}/sites/{site_id}/agent-pages/refresh Refetch existing Agent Pages from your live site now, then re-optimize and republish them, whether or not they changed. Use it after updating pages on your site so AI agents see the new version without waiting for the next scheduled check. Only pages that already have an active Agent Page can be refreshed. The endpoint returns one outcome per requested path, and queued refreshes run in the background. Unless `recheck` is false, a queued page may be checked again a few times over the next hours and republished when what agents are served would change; `recheck_checks` in each result gives how many checks were scheduled. These follow-up checks use no quota. A page whose origin now redirects to another path is not republished: the redirect is recorded, and the page retires at the next scheduled check, within about a day. Limits: 100 paths per request; each path once every 5 minutes; per brand, 500 refreshes per rolling hour and 5,000 per rolling 24 hours. Force Refresh does not add or remove pages, and does not change curated (Adaptive) content at the same path. To take an Agent Page down, use Agent Pages Unpublish. To add one, use Agent Pages Publish. # Agent Pages Force Refresh: Update Pages on Demand Source: https://developers.scrunch.com/api-reference/agent-pages/force-refresh-overview Refetch Agent Pages from your live site now and republish them without waiting for the next scheduled check. ## Overview Agent Pages are kept fresh automatically: Scrunch checks your pages on a schedule and re-optimizes the ones that changed. Force Refresh lets you skip the wait. It refetches the pages you name from your live site, then re-optimizes and republishes them whether or not they changed. Use it right after you publish a change on your site, so AI agents see the new version as soon as possible. *** ## When to use Force Refresh Use this API when you need to: * Push a content update, correction, or pricing change to agents right after it goes live on your site. * Refresh a set of pages after a deploy, from your CI or CMS publish hook. * Re-run optimization on a page you believe is out of date. Force Refresh only refreshes pages that already have an active Agent Page. It doesn't add or remove pages: to add one use [Publish](/api-reference/agent-pages/publish-overview), and to remove one use [Unpublish](/api-reference/agent-pages/unpublish-overview); see [Which API do I need?](#which-api-do-i-need). *** ## Which API do I need? A path on your site can carry two layers of content for AI agents, and the edge serves the first one it finds: 1. **Curated (Adaptive) content**: pages you edit or deploy from the Scrunch dashboard. This includes a reviewed page deployed from Site Optimization and any Agent Page you edit in the Agent Pages content editor, which saves your edit as a curated page at that path. 2. **The Agent Page**: the version Scrunch generates automatically from your live site, kept fresh by the scheduled checks. Force Refresh and the [Agent Pages Unpublish API](/api-reference/agent-pages/unpublish-overview) act on the Agent Page layer only. The [AXP Unpublish API](/api-reference/axp/unpublish) acts on the curated layer only. A page that has both layers needs both unpublishes to be removed completely; after an AXP unpublish alone, agents receive the Agent Page at that path. How you add and remove Agent Pages depends on your setup. If your Site Optimization **Pages** table offers **Serve on Agent Pages**, you select pages one by one; an Agent Pages brand without Site Optimization also works page by page, through the Agent Pages APIs. Otherwise Agent Pages covers your whole site and is configured under **Configure → Universal Optimizations**. On a page-by-page setup, a site serves only its Agent Pages set. With Site Optimization, a site with an empty set serves no Agent Pages. Without it, a site serves every page until its first page is marked or published, and from then on only the set. On a brand without Site Optimization, [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview) refuses to remove the last page of the set (`conflict`), because the site would go back to serving every page, including pages nobody chose. [Agent Pages Publish](/api-reference/agent-pages/publish-overview) has no such refusal: its first page narrows serving to the set you chose. | I want to… | Agent Pages (page-by-page setup) | Agent Pages (whole-site setup) | Curated (Adaptive) content | | - | - | - | - | | Refresh a page | Force Refresh (this page). | Force Refresh (this page). | Edit and redeploy it from the dashboard. Force Refresh doesn't change it. | | Remove a page | [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview), or **Stop serving on Agent Pages** in the Pages table. See [Removing an Agent Page](#removing-an-agent-page). | [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview), or add the path to the **Ignore List** under Configure → Universal Optimizations. | [AXP Unpublish API](/api-reference/axp/unpublish), or archive it from the dashboard. | | Add a new page | [Agent Pages Publish](/api-reference/agent-pages/publish-overview), or **Serve on Agent Pages** in the Pages table. Scheduled discovery does not add unselected pages. Without Site Optimization, on a site with no page marked or published yet, the first one stops serving every page outside the set. | [Agent Pages Publish](/api-reference/agent-pages/publish-overview), including pages your sitemap doesn't list. Otherwise scheduled discovery picks up new pages from your sitemap and from agent traffic. Adding a path to the Priority List is not the way to add one page: the first Priority List entry switches the site to serving only the listed paths and stops serving every other page. | Add it from the dashboard. | The AXP Unpublish API never removes an Agent Page. A path with no curated content returns `not_found`, and on sites below AXP engine 2.1.0 the whole request is refused with `409`. ### Removing an Agent Page For an immediate removal, call [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview) from your CMS or CI. It works on either setup and keeps the page off through later crawls. In the dashboard, **Stop serving on Agent Pages** in the Site Optimization Pages table (page-by-page setup) or the **Ignore List** under **Configure → Universal Optimizations** (whole-site setup) does the same. If the page also has curated content, remove that with the [AXP Unpublish API](/api-reference/axp/unpublish) or archive it from the dashboard. Removing the page from your site also works, but it is slow. Return `404` or `410`, or redirect it, and the scheduled freshness check retires the Agent Page when it next looks at the page. With the default schedule a frequently visited page is rechecked within about 7 days and a rarely visited page within about 30 days; a redirect within your domain needs two consecutive checks, and a redirect to another domain is acted on at the first. For anything time-sensitive, use Unpublish or the dashboard actions above and treat the scheduled check as cleanup. > [!WARNING] > > Don't force-refresh a page you have removed or redirected. The API returns `queued` for a path that now returns `404`, then the refresh fails in the background and the old copy keeps serving until the scheduled check. Unpublish it instead. For a path that now redirects to another path, the page isn't republished: the redirect is recorded as a scheduled check records it, the old copy keeps serving, and the page retires at the next scheduled check, within about a day. A redirect that only changes the host within the same domain (adding or dropping `www.`, or another subdomain) and keeps the path still republishes. *** ## Endpoint | Method | Path | Purpose | | - | - | - | | POST | `/v1/{brand_id}/sites/{site_id}/agent-pages/refresh` | Refresh a list of paths on one site. | The endpoint requires a bearer token with the `optimize` scope. See [Authentication](/getting-started/authentication). *** ## Find your site ID A domain can have more than one site in Scrunch, and only the one serving Agent Pages accepts a refresh. The Site ID in your **Agent Traffic** setup instructions may be a different one: it identifies the site that sends Agent Traffic logs. To get the right ID, call [List Sites](/api-reference/agent-pages/list-sites) and use the `id` of the site for your domain with `agent_pages_active: true`. If no site has it, Agent Pages aren't serving for the brand and the refresh isn't available. Any API key with access to the brand can call List Sites; no scope is required. ```bash theme={null} curl "https://api.scrunchai.com/v1/1234/sites" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` **Response** (abridged): ```json theme={null} { "total": 2, "items": [ { "id": "01JEXAMPLE00000000000000", "domain": "www.example.com", "agent_pages_active": true, "agent_traffic_active": false }, { "id": "01JEXAMPLE00000000000001", "domain": "www.example.com", "agent_pages_active": false, "agent_traffic_active": true } ] } ``` You can also copy it from the **Site ID** line on the Agent Pages page in the Scrunch app. *** ## Request | Field | Type | Required | Description | | - | - | - | - | | `paths` | `string[]` | Yes | Site-relative paths to refresh, for example `/pricing`. **1 to 100 paths** per call. | | `recheck` | `boolean` | No | Defaults to `true`. Each queued page may be checked again a few times over the next hours. Send `false` to refresh each page once only. See [Follow-up checks](#follow-up-checks). | ### Path rules * Each path is trimmed and can be up to 2,048 characters. * Send the public URL path, the one agents request. If your CMS path differs from the public URL (for example AEM `/content/...` versus `/en/about.html`), send the public URL. `.model.json` and other non-HTML exports never have an Agent Page and return `not_found`. * Paths must be site-relative. Full URLs (`https://example.com/pricing`) and protocol-relative URLs (`//example.com/pricing`) are rejected with a `422`. * Paths are normalized the same way Agent Pages are stored: lowercased, with the trailing slash and query string dropped. Duplicates after normalization are merged, keeping the first. * `/` is the homepage. *** ## Response The endpoint returns `202 Accepted`: refreshes run in the background after the response. The body holds one result per requested path, in request order, and the brand's remaining quota. | Field | Type | Description | | - | - | - | | `results[].path` | `string` | The normalized path this outcome applies to. | | `results[].outcome` | `string` | What happened to this path. See the table below. | | `results[].retry_after` | `string \| null` | For `cooldown`, when this path can be refreshed again (ISO 8601, UTC). | | `results[].recheck_checks` | `integer` | How many follow-up checks Scrunch scheduled for this path. See [Follow-up checks](#follow-up-checks). | | `quota.hourly` / `quota.daily` | `object` | The brand's two quota windows, each with `limit`, `remaining`, and `resets_at`. | ### Outcome values | Outcome | Meaning | What to do | | - | - | - | | `queued` | Accepted. The page will be refetched, re-optimized, and republished. | Nothing. | | `not_found` | The site has no active Agent Page at this path. | Check that it is the public URL path, not a CMS or export URL. The page may also have been retired after a `404` at your origin, taken down with [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview), or stopped from the dashboard (Stop serving, or the Ignore List). Force Refresh never adds a page; see [Which API do I need?](#which-api-do-i-need). | | `excluded` | The site's Ignore or Priority List doesn't allow this path. | Update the list in the Scrunch dashboard if the page should be served. | | `cooldown` | This page was refreshed in the last 5 minutes. | Retry after `retry_after`. | | `rate_limited` | The brand's hourly or daily quota ran out partway through this batch. | Retry after `quota.*.resets_at`. | Only `queued` paths count toward any limit. ### Follow-up checks Your origin or CDN can still serve the old version of a page for a short while after you publish a change. A refresh that runs in that window republishes the old page. To catch the update once it goes live, Scrunch may check a queued page again a few times over the next hours, and republishes it only when what agents are served would change. When follow-up checks are enabled, the full schedule is four checks: the first a few minutes after your call, the last between four and seven hours after it, so that it lands after a typical CDN cache of up to four hours has expired. Each result's `recheck_checks` tells you what Scrunch scheduled for that path: | Value | Meaning | | - | - | | `4` | The full schedule of follow-up checks. | | `1` | The last check only. Each brand gets up to 2,000 full schedules per rolling 24 hours; past that, a queued page gets only the last check. | | `0` | No follow-up checks: the path wasn't `queued`, you sent `"recheck": false`, or follow-up checks aren't enabled. | Follow-up checks use no refresh quota and don't start a `cooldown`: only your own refreshes count toward the limits below. A newer refresh of the same path replaces the follow-up checks of an earlier one. To refresh a page once only, send `"recheck": false`: ```json theme={null} { "paths": ["/pricing"], "recheck": false } ``` *** ## Limits | Limit | Value | When exceeded | | - | - | - | | Paths per request | 100 | `422`; nothing is queued. | | Per path | 1 refresh every 5 minutes | That path returns `cooldown`. | | Per brand, hourly | 500 refreshes per rolling hour | Extra paths return `rate_limited`; `429` if nothing could be queued. | | Per brand, daily | 5,000 refreshes per rolling 24 hours | Extra paths return `rate_limited`; `429` if nothing could be queued. | The hourly and daily quotas are shared by all of a brand's sites. Queued refreshes run a few at a time per site, so a batch of 100 completes over several minutes rather than instantly. *** ## Example: refresh pages after a deploy ```bash theme={null} curl -X POST \ "https://api.scrunchai.com/v1/1234/sites/01JEXAMPLE00000000000000/agent-pages/refresh" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "paths": [ "/pricing", "/blog/launch", "/careers" ] }' ``` **Response:** ```json theme={null} { "results": [ { "path": "/pricing", "outcome": "queued", "retry_after": null }, { "path": "/blog/launch", "outcome": "cooldown", "retry_after": "2026-10-07T18:42:10Z" }, { "path": "/careers", "outcome": "not_found", "retry_after": null } ], "quota": { "hourly": { "limit": 500, "remaining": 499, "resets_at": "2026-10-07T19:02:41Z" }, "daily": { "limit": 5000, "remaining": 4987, "resets_at": "2026-10-08T09:15:03Z" } } } ``` *** ## Errors | Status | When | | - | - | | `401` | The API key is missing or invalid. | | `403` | The API key lacks the `optimize` scope or access to the brand. | | `404` | No site with the supplied ULID exists for the brand, or Agent Pages aren't enabled for the brand. | | `409` | Agent Pages aren't active on this site. Check that `site_id` is the site [List Sites](/api-reference/agent-pages/list-sites) reports with `agent_pages_active: true`. Nothing is queued and no quota is used. | | `422` | The request body failed validation (empty `paths`, more than 100 entries, an empty path, a path over 2,048 characters, or a full URL). | | `422` with `"type": "model_attributes_type"` on `body` | The body was not read as JSON, usually because the `Content-Type` header is malformed or duplicated (for example `application/json,application/json`, which some proxies and gateways produce). Send exactly `Content-Type: application/json`. | | `429` | The brand's hourly or daily quota is used up and nothing could be queued, or another refresh request for the same brand is still being processed. The `Retry-After` header gives the seconds to wait (`1` for a request in progress). | | `503` | The refresh couldn't be queued right now. Nothing was queued and no quota was used; retry shortly. | A path that is in cooldown, not found, or excluded doesn't cause an error: the request still returns `202` with those outcomes. *** ## Best practices * **Refresh only what changed.** Send the paths your deploy touched rather than your whole site; the scheduled checks already cover everything else. * **Retry safely.** Re-sending a path within 5 minutes returns `cooldown` and uses no quota. * **Respect the quota.** On `rate_limited` or `429`, wait for `quota.*.resets_at` or the `Retry-After` header before sending more. * **Send one request at a time per brand.** Requests for the same brand are processed one at a time; a request sent while another is in progress gets `429` with `Retry-After: 1`. Batch paths into one request (up to 100) rather than sending many single-path requests in parallel. * **Don't refresh what you removed or redirected.** The path is `queued`, then the refresh fails in the background: a `404` keeps the old copy serving, and a redirect to another path is recorded and retires the page at the next scheduled check, within about a day. See [Removing an Agent Page](#removing-an-agent-page). * **Don't poll for completion yet.** `queued` means the refresh was accepted, not that it finished. Allow a few minutes for a batch to republish. # List Sites Source: https://developers.scrunch.com/api-reference/agent-pages/list-sites /api-reference/openapi.json get /{brand_id}/sites List the brand's sites. A domain can have more than one row, and each route accepts only some of them: pass the `id` with `agent_pages_active: true` to the Agent Pages force refresh, and the one with `agent_traffic_active: true` to agent traffic. # Publish Source: https://developers.scrunch.com/api-reference/agent-pages/publish /api-reference/openapi.json post /{brand_id}/sites/{site_id}/agent-pages/publish Make pages Agent Pages now, including pages your sitemap doesn't list. Each path is fetched from your live site, optimized and served once that finishes, usually within minutes. On a page-by-page setup each page is selected for Agent Pages and counts against your Agent Pages budget. On a page-by-page setup, the site serves only its Agent Pages set. With Site Optimization, a site with an empty set serves no Agent Pages; without it, a site serves every page until its first page is marked or published, so the first publish stops serving every page outside the set. Returns one outcome per requested path. `queued` means the fetch was sent, not that the page is live: if your site doesn't serve the page (for example it answers 404), it stays selected but isn't served until a scheduled check finds it live (about every 30 days) or you send it again. If the send fails, the hourly scheduled check picks the page up, usually within an hour. `warnings` says when a queued page waits on your site: it was retired earlier, or recent checks saw it redirect. A path the Agent Pages Unpublish API put on the Ignore List is published again; a dashboard Ignore List entry or path rule is never overridden (`excluded`). On a whole-site (legacy) setup the page is optimized without being added to any list. A path your CDN doesn't route to the Scrunch edge worker is stored but never served. Limits: 100 paths per request; each path once every 5 minutes; per brand, 500 published paths per rolling hour and 5,000 per rolling 24 hours. These quotas are separate from Force Refresh's and Unpublish's. Publish acts on the Agent Page only. Curated (Adaptive) content at the same path keeps being served, and the response doesn't report it. # Agent Pages Publish: Add Pages on Demand Source: https://developers.scrunch.com/api-reference/agent-pages/publish-overview Make pages Agent Pages now, including pages your sitemap doesn't list, without waiting for scheduled discovery. ## Overview Publish makes the pages you name Agent Pages now. Each path is fetched from your live site, optimized and served to AI agents, usually within minutes. It works for pages your sitemap doesn't list too. Use it from your CMS when a page goes live, or to bring back a page you took down with [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview). Publish acts on the Agent Page only. If the path also has curated (Adaptive) content, agents keep receiving that version, and the response doesn't report it. See [Which API do I need?](/api-reference/agent-pages/force-refresh-overview#which-api-do-i-need). *** ## What happens to a path 1. On a page-by-page setup, the page is marked **Serve on Agent Pages**, exactly as if you selected it in the Site Optimization Pages table, and it counts against your Agent Pages budget. On a whole-site (legacy) setup, nothing is selected, the page isn't added to any list, and no budget applies: the site keeps serving every page, and the path joins the scheduled checks. 2. If [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview) put the path on the Ignore List, that entry is removed. An Ignore List entry or path rule you added in the dashboard is never overridden: the path returns `excluded`. 3. A background job fetches the page from your site, optimizes it and publishes it to the edge. The page is served once that job finishes, usually within minutes. On a page-by-page setup, the site serves only its Agent Pages set: the pages marked in the dashboard or published through this API. With Site Optimization, a site with an empty set serves no Agent Pages. Without it, a site serves every page until its first page is marked or published, and from then on only the set: the first publish stops serving every page outside the set, and Unpublish refuses to remove the last one (`conflict`). ### `queued` is not yet served `queued` means the job was sent, not that the page is live. If the send itself fails, the page is still picked up by the hourly scheduled check, usually within an hour. If your site doesn't serve the page (for example it answers `404`), the job fails. The page stays selected and counts against your Agent Pages budget, but it isn't served until a scheduled check finds it live (about every 30 days) or you send it again. The response can't tell you, because it returns before the fetch, and there is no status endpoint. Publish a page only once it is live on your site. If your site redirects the path to another path, the page isn't published either, and the redirect is recorded as a scheduled check records it; a redirect that only changes the host within the same domain (adding or dropping `www.`, or another subdomain) and keeps the path still publishes. To retry a failed publish, send the path again after its 5-minute cooldown. A `queued` path can also carry `warnings` about its history: | Warning | Meaning | | - | - | | `Retired (), last checked : it serves only once the origin answers 200.` | The page was retired earlier. It serves again only once your site answers `200` for it. `` is `http_gone` (your site answered `404` or `410`), `sitemap_absent` (your sitemap dropped it), `non_html` (it isn't an HTML page) or `admin_retired` (retired by Scrunch). `` is the page's last scheduled check, not the day it was retired. Either part is left out when unknown, down to `Retired: it serves only once the origin answers 200.` | | `Recent checks saw this path redirect to : it serves once a check sees the page answer for itself.` | Recent checks saw the path redirect. It serves once a check sees the page answer without redirecting. `` reads `another URL` when no target was recorded. | ### Pages your sitemap doesn't list Each published path reports `in_sitemap`. A `queued` page your sitemap doesn't list is published as a **manual** Agent Page and carries the warning `Not in the site's sitemap…`. An `already_published` page never carries it: there, `in_sitemap: false` is informational. The sitemap check never removes a manual Agent Page. It stays served until your site answers `404` or redirects it at a scheduled check, or until you call [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview). A `queued` page your sitemap lists is managed by the sitemap, as before: if the sitemap later drops it, the sitemap check can retire it. Publish doesn't change how an `already_published` page is managed. ### Paths your CDN doesn't route to the edge Agents only receive Agent Pages for paths your CDN sends to the Scrunch edge worker. If your CDN rules cover part of the site only (for example `/us-en/*`), a path outside them is published and stored, but never served. The API can't detect this, so check your CDN routing before publishing outside it. *** ## Endpoint | Method | Path | Purpose | | - | - | - | | POST | `/v1/{brand_id}/sites/{site_id}/agent-pages/publish` | Publish a list of paths on one site. | The endpoint requires a bearer token with the `optimize` scope. See [Authentication](/getting-started/authentication). Use the site ID that [List Sites](/api-reference/agent-pages/list-sites) reports with `agent_pages_active: true`; see [Find your site ID](/api-reference/agent-pages/force-refresh-overview#find-your-site-id). *** ## Request | Field | Type | Required | Description | | - | - | - | - | | `paths` | `string[]` | Yes | Site-relative paths to publish, for example `/pricing`. **1 to 100 paths** per call. | Paths follow the same rules as Force Refresh: send the public URL path, site-relative, up to 2,048 characters. Paths are lowercased, the trailing slash and query string are dropped, and duplicates are merged. `/` is the homepage. See [Path rules](/api-reference/agent-pages/force-refresh-overview#path-rules). One difference: `.model.json` and other non-HTML files return `invalid_path` here, not `not_found`. The page is fetched with the spelling you sent first, so a case-sensitive site gets the URL it expects. The query string is dropped from the fetched URL too, so a tracking or session parameter is never fetched. *** ## Response The endpoint returns `200 OK` with one result per requested path, in request order, and the brand's remaining publish quota. | Field | Type | Description | | - | - | - | | `results[].path` | `string` | The normalized path this outcome applies to. | | `results[].outcome` | `string` | What happened to this path. See the table below. | | `results[].retry_after` | `string \| null` | For `cooldown`, when this path can be published again (ISO 8601, UTC). | | `results[].in_sitemap` | `boolean \| null` | For `queued` and `already_published` paths, whether your sitemap lists the page. `null` for other outcomes. | | `results[].warnings` | `string[]` | Why the page may not be served soon, or may be removed later. Empty when there is nothing to report. See [`queued` is not yet served](#queued-is-not-yet-served) and [Pages your sitemap doesn't list](#pages-your-sitemap-doesnt-list). | | `quota.hourly` / `quota.daily` | `object` | The brand's two publish quota windows, each with `limit`, `remaining`, and `resets_at`. | ### Outcome values | Outcome | Meaning | What to do | | - | - | - | | `queued` | The page is an Agent Page now and its fetch was sent. It is served once the fetch and optimization finish. If the send fails, the hourly scheduled check picks the page up, usually within an hour. | Nothing. If it isn't served within the hour, check that the page is live and send it again. | | `already_published` | The page is already being served. Nothing was fetched. On a page-by-page setup, a served page that wasn't marked yet is added to the set, if your budget allows, and counts against your Agent Pages budget. | To pick up a change on your site, use [Force Refresh](/api-reference/agent-pages/force-refresh-overview). | | `excluded` | An Ignore List entry or path rule from the dashboard blocks this path. On a whole-site (legacy) setup with Priority List entries, a path outside them is also `excluded`. The API never overrides the dashboard. | Remove the entry under **Configure → Universal Optimizations**, then retry. | | `over_budget` | Your organization's Agent Pages budget is full (page-by-page setups only). In a batch, the first paths that fit are queued. Nothing was written for this path. | Stop serving another page, or ask your account team for more, then retry. | | `invalid_path` | Not a web page (a file such as `.pdf`, `.json` or `.model.json`), or a path the page list can't store. | Send the public URL path of an HTML page. | | `cooldown` | This path was published in the last 5 minutes. | Retry after `retry_after`. | | `rate_limited` | The brand's hourly or daily quota ran out partway through this batch. | Retry after `quota.*.resets_at`. | Only `queued` paths count toward the quota. *** ## Limits | Limit | Value | When exceeded | | - | - | - | | Paths per request | 100 | `422`; nothing is published. | | Per path | 1 publish every 5 minutes | That path returns `cooldown`. | | Per brand, hourly | 500 paths per rolling hour | Extra paths return `rate_limited`; `429` if nothing could be published. | | Per brand, daily | 5,000 paths per rolling 24 hours | Extra paths return `rate_limited`; `429` if nothing could be published. | | Agent Pages budget | Your organization's plan (page-by-page setups only) | Extra paths return `over_budget`. | The quotas are shared by all of a brand's sites and are separate from the Force Refresh and Unpublish quotas. *** ## Example: publish new pages ```bash theme={null} curl -X POST \ "https://api.scrunchai.com/v1/1234/sites/01JEXAMPLE00000000000000/agent-pages/publish" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "paths": [ "/pricing", "/launch/fall-event", "/about", "/brochure.pdf" ] }' ``` **Response:** ```json theme={null} { "results": [ { "path": "/pricing", "outcome": "queued", "retry_after": null, "in_sitemap": true, "warnings": [] }, { "path": "/launch/fall-event", "outcome": "queued", "retry_after": null, "in_sitemap": false, "warnings": [ "Retired (http_gone), last checked 2026-10-20: it serves only once the origin answers 200.", "Not in the site's sitemap. Published as a manual Agent Page: it is not removed by the sitemap check, only by an origin 404 or redirect, or the unpublish API." ] }, { "path": "/about", "outcome": "already_published", "retry_after": null, "in_sitemap": true, "warnings": [] }, { "path": "/brochure.pdf", "outcome": "invalid_path", "retry_after": null, "in_sitemap": null, "warnings": [] } ], "quota": { "hourly": { "limit": 500, "remaining": 498, "resets_at": "2026-10-28T15:02:41Z" }, "daily": { "limit": 5000, "remaining": 4987, "resets_at": "2026-10-29T09:15:03Z" } } } ``` *** ## Errors | Status | When | | - | - | | `401` | The API key is missing or invalid. | | `403` | The API key lacks the `optimize` scope or access to the brand. | | `404` | No site with the supplied ULID exists for the brand, or Agent Pages aren't enabled for the brand. | | `409` | Agent Pages aren't active on this site. Check that `site_id` is the site [List Sites](/api-reference/agent-pages/list-sites) reports with `agent_pages_active: true`. Nothing is published and no quota is used. | | `422` | The request body failed validation (empty `paths`, more than 100 entries, an empty path, a path over 2,048 characters, or a full URL). A malformed or duplicated `Content-Type` header also returns `422`; send exactly `Content-Type: application/json`. | | `429` | The brand's hourly or daily publish quota is used up and nothing could be published, or another publish request for the same brand is still being processed. The `Retry-After` header gives the seconds to wait (`1` for a request in progress). | A path that is excluded, over budget, invalid or in cooldown doesn't cause an error: the request still returns `200` with those outcomes. *** ## Best practices * **Publish once the page is live.** The fetch runs right after the response; a page your site doesn't serve yet fails silently. Read `warnings` on `queued` paths: a retired or redirecting page waits for your site to answer for it. * **Retry safely.** Re-sending a served path returns `already_published` and fetches nothing. On a page-by-page setup it is also added to the set, if it wasn't already and your budget allows. Re-sending a `queued` path within 5 minutes returns `cooldown`, or `already_published` once it is served; after that it fetches the page again, which is how you retry a failed publish. * **Send one request at a time per brand.** A request sent while another publish for the brand is in progress gets `429` with `Retry-After: 1`. Batch paths into one request (up to 100). * **Publish after Unpublish.** A path taken down with [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview) can be published again with this API. A path you put on the Ignore List in the dashboard can't: remove it there first. * **Check curated content.** If the dashboard shows an edited or deployed version at the path, agents keep receiving that version instead of the published Agent Page. # Unpublish Source: https://developers.scrunch.com/api-reference/agent-pages/unpublish /api-reference/openapi.json post /{brand_id}/sites/{site_id}/agent-pages/unpublish Stop serving Agent Pages now. Each path is added to the site's Ignore List, so it stays unpublished through later crawls, sitemap checks and page selections, and its copy is removed from the edge within minutes, or before the response with `immediate: true`. Returns one outcome per requested path. A path that has nothing to remove doesn't cause an error. Limits: 100 paths per request; each path once every 5 minutes; per brand, 100 unpublished paths per rolling hour and 1,000 per rolling 24 hours. These quotas are separate from Force Refresh's. Unpublish acts on the Agent Page only. Curated (Adaptive) content at the same path keeps being served, and the response doesn't report it; remove it with the AXP Unpublish API. # Agent Pages Unpublish: Stop Serving Pages on Demand Source: https://developers.scrunch.com/api-reference/agent-pages/unpublish-overview Take Agent Pages off the edge now and keep them off, without waiting for the next scheduled check. ## Overview Unpublish stops serving the Agent Pages you name. Each path is added to the site's **Ignore List**, so it stays unpublished: later crawls, sitemap checks and page selections don't bring it back. Its copy is then removed from the edge, within minutes or, with `immediate: true`, before the response. Use it from your CMS when a page is taken down, or when an Agent Page must stop being served right away. Unpublish acts on the Agent Page only. If the path also has curated (Adaptive) content, agents keep receiving that version after the unpublish, and the response doesn't report it. Remove it with the [AXP Unpublish API](/api-reference/axp/unpublish). See [Which API do I need?](/api-reference/agent-pages/force-refresh-overview#which-api-do-i-need). *** ## What happens to a path 1. The path is added to the site's Ignore List under **Configure → Universal Optimizations**, as a single page (its subpages are not affected). 2. The Agent Page is archived. On a page-by-page setup, the page is also no longer marked **Serve on Agent Pages**, so it stops counting against your Agent Pages budget. 3. Its copy is deleted from the edge. Without `immediate`, a background job does this within minutes of the response. The API never changes a rule you set in the dashboard. If the path is itself an entry you added to the Priority List in the dashboard, either a page entry or a prefix entry, it returns `conflict` and nothing is written. Only that exact path conflicts: a page under a prefix entry (`/blog/post` under `/blog`) can still be unpublished, because the Ignore List wins over the Priority List. Unpublishing doesn't change the site's Agent Pages settings published to the edge, and doesn't touch other pages. Curated (Adaptive) content at the same path keeps serving, and the response doesn't report it. ### How long a copy can still be served Once its copy is deleted, the edge stops serving the Agent Page within about 60 seconds. A cache in front of the edge can still hold a copy it already served to an AI agent, and serves it until it expires: | Platform | Edge copy gone | Cached copies in front of the edge | | - | - | - | | Cloudflare | About 60 seconds after the delete | None by default. A cache you add in front of the worker can keep a copy for up to 1 hour. | | Akamai | About 60 seconds after the delete | Your Akamai property can keep serving a copy it cached, for as long as its caching rules allow. Copies held for 2 to 4 hours have been observed. | Without `immediate`, add the few minutes the background job takes to delete the copy. Scrunch doesn't purge your CDN cache; purge the URL yourself if it can't wait. ### Publishing the page again An unpublished path stays off until you publish it again. [Agent Pages Publish](/api-reference/agent-pages/publish-overview) does it in one call: it removes the Ignore List entry this API added and, on a page-by-page setup, marks the page **Serve on Agent Pages** again. In the dashboard, remove the path from the **Ignore List** under **Configure → Universal Optimizations**, then, on a page-by-page setup, select **Serve on Agent Pages** for it again in the Site Optimization Pages table. Selecting it while the path is still on the Ignore List doesn't serve it. *** ## Endpoint | Method | Path | Purpose | | - | - | - | | POST | `/v1/{brand_id}/sites/{site_id}/agent-pages/unpublish` | Unpublish a list of paths on one site. | The endpoint requires a bearer token with the `optimize` scope. See [Authentication](/getting-started/authentication). Use the site ID that [List Sites](/api-reference/agent-pages/list-sites) reports with `agent_pages_active: true`; see [Find your site ID](/api-reference/agent-pages/force-refresh-overview#find-your-site-id). *** ## Request | Field | Type | Required | Description | | - | - | - | - | | `paths` | `string[]` | Yes | Site-relative paths to unpublish, for example `/pricing`. **1 to 100 paths** per call. | | `immediate` | `boolean` | No | Delete the edge copies before responding instead of within minutes. Default `false`. | Paths follow the same rules as Force Refresh: send the public URL path, site-relative, up to 2,048 characters. Paths are lowercased, the trailing slash and query string are dropped, and duplicates are merged. `/` is the homepage. See [Path rules](/api-reference/agent-pages/force-refresh-overview#path-rules). *** ## Response The endpoint returns `200 OK` with one result per requested path, in request order, and the brand's remaining unpublish quota. | Field | Type | Description | | - | - | - | | `results[].path` | `string` | The normalized path this outcome applies to. | | `results[].outcome` | `string` | What happened to this path. See the table below. | | `results[].retry_after` | `string \| null` | For `cooldown`, when this path can be unpublished again (ISO 8601, UTC). | | `results[].edge` | `string \| null` | With `immediate: true`, for every requested path whose Agent Page is no longer served but whose copy was still at the edge, whatever its outcome: the result of the edge delete. See [Edge results](#edge-results). | | `quota.hourly` / `quota.daily` | `object` | The brand's two unpublish quota windows, each with `limit`, `remaining`, and `resets_at`. | ### Outcome values | Outcome | Meaning | What to do | | - | - | - | | `unpublished` | The Agent Page was being served at the edge. It is on the Ignore List now and its edge copy is removed. | Nothing. | | `already_unpublished` | No Agent Page was being served at this path: the Ignore List already covers it, the Agent Page was already retired, or it was never published to the edge. The path is added to the Ignore List if it wasn't on it, so scheduled checks don't publish it again. | Nothing. A retry of an earlier unpublish returns this. | | `not_found` | The site has no Agent Page at this path, and none is scheduled. Nothing is written. | Check that it is the public URL path, not a CMS or export URL. If the path serves curated content, use the [AXP Unpublish API](/api-reference/axp/unpublish). | | `conflict` | The path is itself an entry you added to the Priority List in the dashboard, either a page entry or a prefix entry. Pages under a prefix entry don't conflict. This includes an entry added while the request was running. On a brand without Site Optimization, when the request would remove every remaining Priority List entry on the site, those paths also return `conflict`, because a site with no entries serves every page. Nothing is written and no quota is used. | Change the Priority List under Configure → Universal Optimizations, then retry. | | `cooldown` | This path was taken off the Ignore List and unpublished again within 5 minutes of its last unpublish. A plain resend returns `already_unpublished` instead. | Retry after `retry_after`. | | `rate_limited` | The brand's hourly or daily quota ran out partway through this batch. | Retry after `quota.*.resets_at`. | Only `unpublished` and `already_unpublished` paths count toward the quota, and only when the path was not already on the Ignore List. `conflict` paths never do. ### Edge results Reported only with `immediate: true`, for every requested path whose Agent Page is no longer served but whose copy was still at the edge, whatever its outcome. That includes an `already_unpublished` path whose copy an earlier call left behind, so an `immediate` retry cleans it up. `null` means there was no copy to delete. A page this call left serving (for example `conflict`, `cooldown` or `rate_limited` on a live page) is never deleted and reports `null`. For an unpublished path, the page stays unpublished whatever `edge` says: it is on the Ignore List and won't be republished. | `edge` | Meaning | | - | - | | `deleted` | The edge copy is gone. | | `failed` | The edge delete failed for this path. The unpublish still holds, and the background job retries the delete within minutes. If the delete fails as a whole, every path with an edge copy reports `failed`. | | `deferred` | The site has no CDN platform configured, so no edge delete was attempted. | *** ## Limits | Limit | Value | When exceeded | | - | - | - | | Paths per request | 100 | `422`; nothing is unpublished. | | Per path | 1 unpublish every 5 minutes | A path taken off the Ignore List and unpublished again within 5 minutes returns `cooldown`. A plain resend returns `already_unpublished`. | | Per brand, hourly | 100 paths per rolling hour | Extra paths return `rate_limited`; `429` if nothing could be unpublished. | | Per brand, daily | 1,000 paths per rolling 24 hours | Extra paths return `rate_limited`; `429` if nothing could be unpublished. | The quotas are shared by all of a brand's sites and are separate from the Force Refresh quotas. For a bulk cleanup, use the Ignore List in the dashboard, which also accepts a CSV upload. *** ## Example: take a page down right away ```bash theme={null} curl -X POST \ "https://api.scrunchai.com/v1/1234/sites/01JEXAMPLE00000000000000/agent-pages/unpublish" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "paths": [ "/pricing", "/old-campaign", "/careers" ], "immediate": true }' ``` **Response:** ```json theme={null} { "results": [ { "path": "/pricing", "outcome": "unpublished", "retry_after": null, "edge": "deleted" }, { "path": "/old-campaign", "outcome": "already_unpublished", "retry_after": null, "edge": null }, { "path": "/careers", "outcome": "not_found", "retry_after": null, "edge": null } ], "quota": { "hourly": { "limit": 100, "remaining": 99, "resets_at": "2026-10-28T15:02:41Z" }, "daily": { "limit": 1000, "remaining": 987, "resets_at": "2026-10-29T09:15:03Z" } } } ``` *** ## Errors | Status | When | | - | - | | `401` | The API key is missing or invalid. | | `403` | The API key lacks the `optimize` scope or access to the brand. | | `404` | No site with the supplied ULID exists for the brand, or Agent Pages aren't enabled for the brand. | | `409` | Agent Pages aren't active on this site. Check that `site_id` is the site [List Sites](/api-reference/agent-pages/list-sites) reports with `agent_pages_active: true`. Nothing is unpublished and no quota is used. | | `422` | The request body failed validation (empty `paths`, more than 100 entries, an empty path, a path over 2,048 characters, or a full URL). A malformed or duplicated `Content-Type` header also returns `422`; send exactly `Content-Type: application/json`. | | `429` | The brand's hourly or daily unpublish quota is used up and nothing could be unpublished, or another unpublish request for the same brand is still being processed. The `Retry-After` header gives the seconds to wait (`1` for a request in progress). | | `5xx` | An unexpected server error. The paths may already be unpublished; retrying is safe. | A path that is in cooldown, not found, or in conflict doesn't cause an error: the request still returns `200` with those outcomes. A failed edge delete doesn't either: those paths report `edge: "failed"`. *** ## Best practices * **Retry safely.** Re-sending a path returns `already_unpublished` and changes nothing on the Ignore List. With `immediate: true`, a retry also deletes any edge copy still left from the earlier call and reports it in `edge`. * **Use `immediate` when it matters.** It makes the request slower, so leave it off for routine takedowns; the background job removes the copy within minutes. * **Send one request at a time per brand.** A request sent while another unpublish for the brand is in progress gets `429` with `Retry-After: 1`. Batch paths into one request (up to 100). * **Remove curated content too.** If the dashboard shows an edited or deployed version at the path, unpublish it with the [AXP Unpublish API](/api-reference/axp/unpublish) as well, or agents keep receiving it after the Agent Pages unpublish. # Get Agent Traffic Source: https://developers.scrunch.com/api-reference/agent-traffic/get-agent-traffic /api-reference/openapi.json get /{brand_id}/sites/{site_id}/agent-traffic Retrieve aggregated bot and AI agent traffic data for a specific site. This endpoint provides visibility into how AI agents and bots are accessing your web properties. Use it to analyze traffic patterns, identify top agents, and understand crawl behavior over time. ## Available Dimensions The following dimensions can be included in the `fields` parameter to group results: | Field | Description | |-------|-------------| | `date` | Daily timestamp for the traffic record | | `site` | The site's registered domain, lowercase, without scheme or www. | | `path` | URL path on the site | | `agent_source` | The source/origin of the agent (e.g., OpenAI, Google, Anthropic) | | `agent_type` | Classification of the agent type | ## Metrics Traffic counts are automatically included in the response based on the selected dimensions. # Agent Traffic API: Monitor AI Bot Crawls Source: https://developers.scrunch.com/api-reference/agent-traffic/overview Aggregate AI bot and crawler traffic across your sites by date, path, agent source, and bot type to monitor retrieval, training, and indexing activity. ## Overview The Agent Traffic API provides aggregated analytics on AI bot activity across your websites. Track which AI platforms are crawling your content, what pages they access, and understand patterns in retrieval, training, and indexing behavior. This API is optimized for **time-series analysis** and **bot classification**, making it ideal for SEO teams, content strategists, and developers building AI visibility monitoring into their workflows. Each request returns aggregated bot traffic metrics grouped by the dimensions you select. *** ## What the Agent Traffic API includes The Agent Traffic API returns aggregated metrics including: * Request counts by bot source * Traffic patterns by date or week * Bot activity by page path * Classification by bot type (retrieval, training, indexer) These metrics can be grouped by dimensions including: * Date (day or week buckets) * Site domain * URL path * Agent source (e.g., chatgpt-user, claudebot, gptbot) * Agent type (retrieval, training, indexer) All results are **aggregated summaries** optimized for trend analysis and monitoring. *** ## When to use the Agent Traffic API Use the Agent Traffic API when you need: * Weekly or daily bot traffic reporting * Trend analysis of AI crawler behavior over time * Path-level breakdowns of bot activity * Bot classification by retrieval vs training purposes * Data for SEO dashboards monitoring AI visibility * Automated alerts based on traffic patterns The Agent Traffic API is designed to answer questions like: "Which AI bots are crawling my content?" and "How is bot traffic trending across different sections of my site?" *** ## When not to use the Agent Traffic API The Agent Traffic API is not appropriate if you need: * Raw access log entries * Individual request details (user agents, IP addresses, timestamps) * Real-time streaming data * Non-bot traffic analytics For CDN setup and log configuration, see the [Agent Traffic Integration Guide](/integrations/agent-traffic). *** ## Example query ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/sites/01JW849S5DJZ3CCE4DA6TFMYEY/agent-traffic?start_date=2025-01-01&end_date=2025-01-31&fields=date,agent_source,agent_type&time_bucket=week" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` **Response:** ```json theme={null} { "meta": { "start_date": "2025-01-01", "end_date": "2025-01-31", "time_bucket": "week" }, "data": [ { "date": "2025W01", "agent_source": "chatgpt-user", "agent_type": "retrieval", "requests": 1247 }, { "date": "2025W01", "agent_source": "claudebot", "agent_type": "training", "requests": 892 } ] } ``` *** ## Available dimensions | Field | Description | Example Values | | - | - | - | | `date` | Timestamp bucket | `20250115` (day) or `2025W03` (week) | | `site` | Registered domain of the site (lowercase, no scheme or `www.`) | `example.com` | | `path` | URL path | `/blog/article` | | `agent_source` | Bot identifier | `chatgpt-user`, `claudebot`, `gptbot` | | `agent_type` | Bot category | `retrieval`, `training`, `indexer` | The `site` value comes from the domain registered for the site in Scrunch, not from the request's host header. For example, a site registered as `https://www.example.com` reports `example.com`. *** ## Time bucketing Control the granularity of date aggregation using the `time_bucket` parameter: * `day` (default): Daily aggregation with dates formatted as `YYYYMMDD` * `week`: Weekly aggregation with dates formatted as `YYYYWW` (ISO week number) Weekly buckets reduce result size and are recommended for long-range trend analysis. *** ## Path filtering Use the `path` parameter to filter results by URL path prefix: ```bash theme={null} # Only show bot traffic to blog articles ?path=/blog/ # Only show traffic to a specific section ?path=/products/widgets ``` Path matching uses prefix-based filtering with SQL LIKE patterns (`path LIKE '/blog/%'`). All user input is properly escaped to prevent SQL injection. *** ## Limits and performance considerations * Maximum rows per request: 100,000 * Default limit: 10,000 rows * Results are pre-aggregated for fast retrieval * Use pagination (`limit` and `offset`) for large result sets Results are sorted by `requests` in descending order. Rows with the same request count are then sorted by each requested dimension, so paging with `offset` returns consistent pages without repeated or skipped rows. For best performance: * Use weekly bucketing when possible to reduce cardinality * Keep path filters specific to reduce result size * Request only the dimensions you need *** ## Security and validation The Agent Traffic API implements strict security measures: * **Site ID validation**: All site IDs are validated against ULID format using regex * **Parameter validation**: All query parameters are validated before SQL generation * **SQL injection prevention**: Path filters use escaped LIKE patterns with no direct string concatenation * **Authentication**: All requests require valid bearer token authentication *** ## Best practices * Use `time_bucket=week` for trend analysis spanning more than 30 days * Filter by `path` when analyzing specific site sections * Group by `agent_type` to distinguish retrieval bots from training crawlers * Run separate queries for different reporting needs rather than over-selecting dimensions * Monitor `agent_source` trends to identify new AI platforms crawling your content *** ## Typical use cases Teams commonly use the Agent Traffic API to: * Monitor which AI platforms are indexing their content * Identify pages with high bot traffic for SEO optimization * Track changes in crawler behavior after content updates * Build dashboards showing AI visibility by site section * Alert on unusual bot traffic patterns * Analyze the impact of robots.txt changes on AI crawler access *** ## Prerequisites Before using the Agent Traffic API, you must: 1. Configure your CDN or hosting provider to send access logs to Scrunch 2. Verify your site is properly configured in your Scrunch account 3. Get your site ID from [List Sites](/api-reference/agent-pages/list-sites): use the `id` of the site with `agent_traffic_active: true` > [card] [Set up Agent Traffic logging](/integrations/agent-traffic) > > Configure your CDN integration → # Send Custom Agent Traffic Events Source: https://developers.scrunch.com/api-reference/agent-traffic/post-custom-web-traffic POST https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic POST AI bot and agent traffic events from any web host, CDN, or edge function to Scrunch using the custom web-traffic ingestion endpoint. Send bot and AI agent traffic data from any platform to Scrunch AI. This endpoint accepts traffic events in JSON or NDJSON format and automatically classifies bots based on user agent strings. ## Endpoint ``` POST https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic ``` ## Authentication Authenticate using the `X-Api-Key` header with a JWT token provided in the Scrunch AI dashboard when creating a site with the "API" platform. To generate the `X-Api-Key`, add a new website on the Agent Traffic page and select `API` as your platform. ```bash theme={null} X-Api-Key: ``` ## Path parameters | Parameter | Type | Required | Description | | - | - | - | - | | `site_id` | string | Yes | The Site ID (ULID format) assigned in the dashboard. | The `platform_id` is always `custom` for this endpoint. ## Request headers | Header | Value | Required | Description | | - | - | - | - | | `X-Api-Key` | `` | Yes | Authentication token from the dashboard. | | `Content-Type` | `application/json` or `application/x-ndjson` | Yes | Use `application/json` for a single event, or `application/x-ndjson` for multiple events (one JSON object per line). | ## Request body The body can be either a **single JSON object** or **NDJSON** (newline-delimited JSON, one object per line). ### Fields | Field | Type | Required | Description | | - | - | - | - | | `domain` | string | Yes | The domain of the site (e.g. `example.com`). | | `user_agent` | string | Yes | The full User-Agent string of the request. | | `url` | string | Yes | The full URL that was requested (e.g. `https://example.com/page`). | | `path` | string | Yes | The URL path (e.g. `/page`). | | `method` | string | Yes | The HTTP method (e.g. `GET`, `POST`). | | `status_code` | integer | Yes | The HTTP response status code (e.g. `200`, `404`). | | `timestamp` | integer / float | Yes | Unix epoch timestamp in **seconds** (e.g. `1700000000`). | | `response_time` | integer | No | Response time in milliseconds. | | `ip` | string | No | The IP address of the client making the request. | ## Example: single event (JSON) ```bash theme={null} curl -X POST "https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic" \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_API_KEY" \ -d '{ "domain": "example.com", "user_agent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)", "url": "https://example.com/blog/post", "path": "/blog/post", "method": "GET", "status_code": 200, "timestamp": 1700000000, "response_time": 120, "ip": "203.0.113.1" }' ``` ## Example: batch events (NDJSON) Send multiple events in a single request using newline-delimited JSON. Each line is a complete JSON object. ```bash theme={null} curl -X POST "https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic" \ -H "Content-Type: application/x-ndjson" \ -H "X-Api-Key: YOUR_API_KEY" \ -d '{"domain":"example.com","user_agent":"Mozilla/5.0 (compatible; GPTBot/1.0)","url":"https://example.com/page-1","path":"/page-1","method":"GET","status_code":200,"timestamp":1700000000} {"domain":"example.com","user_agent":"Mozilla/5.0 (compatible; ClaudeBot/1.0)","url":"https://example.com/page-2","path":"/page-2","method":"GET","status_code":200,"timestamp":1700000060,"response_time":95,"ip":"198.51.100.42"}' ``` ## Responses | Status Code | Description | | - | - | | 200 | Events accepted and queued for processing. | | 401 | Unauthorized — invalid or missing API key. | | 422 | Validation error — check the request body against the schema above. | | 429 | Rate limited — wait and retry. Respect the `Retry-After` header if present. | | 500 | Internal server error. | ### Success response (200) ```json theme={null} { "status": "ok" } ``` ## Notes * **Batch size**: For NDJSON batches, keep each request under \~1 MB uncompressed. * **Timestamp**: Must be a Unix epoch in seconds. Both integers and floats are accepted. Invalid timestamps will fall back to the current server time. * **Bot detection**: The `user_agent` field is used to automatically identify and classify the bot/AI agent. Pass the original User-Agent string from the incoming request. * **Activation**: After creating a site with the "API" platform in the dashboard, it starts in "pending" status. Once the first valid request is received, the site automatically transitions to "active" within 5 minutes. ## Best practices * Use NDJSON for batch uploads to reduce request overhead * Keep batch sizes under 1 MB for optimal performance * Always pass the original User-Agent string for accurate bot classification * Monitor response status codes and implement retry logic for 429 and 500 errors * Use the `response_time` field to track performance metrics alongside bot traffic # Disable AI Referrals Connection Source: https://developers.scrunch.com/api-reference/ai-referrals/disable-ai-referrals-connection /api-reference/openapi.json delete /{brand_id}/ai-referrals/connections/{connection_id} Soft-disable a connection. Previously pushed events are retained but further pushes are rejected with `410 Gone` and the dashboard stops reading from this connection. # List AI Referrals Connections Source: https://developers.scrunch.com/api-reference/ai-referrals/list-ai-referrals-connections /api-reference/openapi.json get /{brand_id}/ai-referrals/connections List AI Referrals push connections registered for this brand. Scope is limited to push connections only — Google Analytics integrations live in a separate system and are not returned here, even though they can block a register call with `409`. # AI Referrals API: Send traffic from any analytics tool Source: https://developers.scrunch.com/api-reference/ai-referrals/overview Send daily AI referral traffic from Adobe Analytics, a warehouse or any other analytics tool, and see it in Scrunch's AI Referrals, Explorer and Scrunchie. ## Overview Send Scrunch the visits your website gets from AI assistants (ChatGPT, Perplexity, Claude, Gemini and others), straight from the analytics tool you already use: Adobe Analytics, a data warehouse, a log pipeline, anything that can count daily sessions by referrer and page. You send one row per day, referrer and page. Scrunch shows it on the **AI Referrals** page, and in the **Explorer** and **Scrunchie** where AI referrals are on for your brand. > [!WARNING] > > **Beta.** Talk to your Scrunch team before you build against this API: they turn it on for your brand and help you set it up. Until it's on, every endpoint returns `404`. > [!NOTE] > > Using **Google Analytics 4**? Connect it in **Integrations** instead; you don't need this API. A website reads from one source at a time, so a website with Google Analytics connected can't also use this API (and the other way around). *** ## How it works 1. **Register the website.** One call per website returns a `connection_id`. 2. **Send daily rows** to that connection, on whatever schedule suits you: a daily job, a pipeline, or several times a day. Sending a row again replaces it, so retries and corrections are safe. 3. **See the data** in Scrunch. A day shows once it's over (UTC). All endpoints live under `https://api.scrunchai.com/v1`. | Method | Path | What it does | | - | - | - | | `POST` | `/{brand_id}/ai-referrals/connections` | Register a website. | | `GET` | `/{brand_id}/ai-referrals/connections` | List the brand's connections and their last push or error. | | `DELETE` | `/{brand_id}/ai-referrals/connections/{connection_id}` | Disable a connection: its data stops showing and new rows are refused. | | `POST` | `/{brand_id}/ai-referrals/connections/{connection_id}/events` | Send rows. | *** ## Authentication Send an API key as a Bearer token. Create one in Scrunch under **API Keys**: * `configure` scope to register, disable and send rows. * `query` scope to list connections. ```bash theme={null} export SCRUNCH_API_TOKEN="your-key" ``` *** ## Register a website ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/1234/ai-referrals/connections" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"website": "example.com", "provider": "custom"}' ``` * `website` must be one of the brand's websites in Scrunch. * `provider` is a label for where the data comes from: use `"custom"` for any tool. `"adobe_analytics"` is also accepted. Both are read the same way. The response includes the connection `id`: use it as `connection_id` when you send rows. Each website has one active connection at a time. *** ## Send rows Send a JSON array (`Content-Type: application/json`) or one row per line (`Content-Type: application/x-ndjson`), up to **10,000 rows** and **5 MB** per call, and up to **120 calls a minute** per brand. ```bash theme={null} curl -X POST \ "https://api.scrunchai.com/v1/1234/ai-referrals/connections/01JX2Y6E8H1AKQ8V0W7G4D9SXT/events" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '[ { "date": "2026-05-20", "raw_referrer_value": "chatgpt.com", "raw_page_value": "/pricing", "sessions": 298, "pageviews": 412, "transactions": 7, "purchase_revenue": 1842.50, "currency_code": "USD" }, { "date": "2026-05-20", "raw_referrer_value": "perplexity.ai", "raw_page_value": "/blog/launch-notes", "sessions": 71, "pageviews": 88 } ]' ``` ```json theme={null} { "accepted": 2, "rejected": 0, "errors": [] } ``` A row whose referrer isn't an AI assistant (`google.com`, say) is counted in `rejected` with its reason in `errors`; the rest of the call still goes through. ### Row fields | Field | Type | Required | Description | | - | - | - | - | | `date` | `YYYY-MM-DD` | Yes | The UTC day the row covers. Not in the future, at most five years back. | | `raw_referrer_value` | string | Yes | The referrer as your tool reports it, e.g. `chatgpt.com`. Don't map it yourself: Scrunch matches it to the AI assistant. | | `raw_page_value` | string | Yes | The landing page, as a path (`/pricing`) or a full URL. Stored as sent; Scrunch reads it by its path, without the query. | | `sessions` | integer | No | Sessions from that referrer on that page that day. | | `pageviews` | integer | No | Page views in those sessions. | | `transactions` | integer | No | Purchases in those sessions. | | `purchase_revenue` | number | No | Revenue from those purchases. | | `currency_code` | string | With revenue | ISO 4217 code of the revenue, e.g. `USD`. Required when `purchase_revenue` isn't 0. A connection keeps one currency. | | `users` | integer | No\* | Users who arrived from that referrer that day. | | `new_users` | integer | No\* | Of those, users new to the website. At most `users`. | | `engaged_sessions` | integer | No\* | Engaged sessions, by your tool's definition. At most `sessions`. | | `engagement_seconds` | number | No\* | Total engagement time of the row's sessions, in seconds. | | `key_events` | integer | No\* | Conversion events in the row's sessions. | | `converted_sessions` | integer | No\* | Sessions with at least one conversion. At most `sessions`. | | `batch_id` | string | No | Your own id for the run that sent the row, to trace it later. | \* **All six or none.** Send `users`, `new_users`, `engaged_sessions`, `engagement_seconds`, `key_events` and `converted_sessions` together on every row, or leave all six out. Leave them out and Scrunch shows traffic and revenue only for that website. A connection keeps the choice its first rows made: to change it, disable the connection, register the website again and send its history the new way. **Replacing rows.** A row is identified by `date`, `raw_referrer_value` and `raw_page_value`. Sending the same three again replaces the earlier values. Pages are compared as sent, so `https://www.example.com/pricing` and `/pricing` are two rows (both count as `/pricing` in Scrunch). *** ## Status codes | Status | Meaning | | - | - | | `200` | Rows received. The body says how many were `accepted` and `rejected`, and why. | | `201` | Website registered. | | `400` | The body isn't valid JSON or NDJSON, the provider or website isn't valid, or one call mixes rows with and without the six optional fields, or two currencies. | | `404` | The brand or connection doesn't exist, or the API isn't on for the brand yet. | | `409` | The website already has an active connection or Google Analytics connected, or the rows don't match what the connection already sends (the six optional fields, or the currency). | | `410` | The connection is disabled. Register the website again. | | `413` | More than 10,000 rows or 5 MB. Split the call. | | `422` | Some rows aren't valid. Nothing from the call is stored; `detail.errors` lists each bad row by its number. | | `429` | More than 120 calls a minute for the brand. Nothing is stored; wait the seconds in the `Retry-After` header and send it again. | When a call stores nothing because of its rows (a `400`, `409` or `422`, or every row rejected), the reason is kept on the connection as `last_push_error`, and `last_pushed_at` says when rows last arrived. Listing connections shows both; the next call that stores rows clears the error. *** ## Tips * **Send finished days.** A day shows in Scrunch once it's over; re-send a day if your tool revises it. * **Retry freely.** Sending the same rows again replaces them, so a retry never double-counts. * **Keep raw values.** Send referrers and pages as your tool reports them. * **Set `batch_id`** to tie rows to the run that sent them. # Push AI Referrals Events Source: https://developers.scrunch.com/api-reference/ai-referrals/push-ai-referrals-events /api-reference/openapi.json post /{brand_id}/ai-referrals/connections/{connection_id}/events Push a batch of pre-aggregated daily AI-referral events for a registered connection. Accepts `application/json` (a JSON array of events) or `application/x-ndjson` (one event per line). The upsert key is `(date, raw_referrer_value, raw_page_value)` — re-sending the same tuple replaces the prior values, so backfills and corrections are safe to retry. Limits: - Maximum 10,000 events per batch. - Maximum 5 MB request body. # Register AI Referrals Connection Source: https://developers.scrunch.com/api-reference/ai-referrals/register-ai-referrals-connection /api-reference/openapi.json post /{brand_id}/ai-referrals/connections Register one of the brand's websites to send AI referral rows for. Rows can only be sent once a connection exists. A website reads from one source at a time: one with Google Analytics connected, or an active connection already, returns `409`. Use provider `custom` for any analytics tool; `adobe_analytics` is also accepted. # Archive Competitor Source: https://developers.scrunch.com/api-reference/archive-competitor /api-reference/openapi.json delete /brands/{brand_id}/competitors/{competitor_id} Archive a competitor # Archive Persona Source: https://developers.scrunch.com/api-reference/archive-persona /api-reference/openapi.json delete /brands/{brand_id}/personas/{persona_id} Archive a persona. Its active prompts are paused (not archived): collection stops but their collected history stays available on the API, and they can be resumed after the persona is restored or the prompts reassigned. # Archive Prompt Source: https://developers.scrunch.com/api-reference/archive-prompt /api-reference/openapi.json delete /{brand_id}/prompts/{prompt_id} Archives a prompt (soft delete). The prompt will no longer be tracked but historical data is preserved. Requires the `configure` scope. # Get Site Audit Score Source: https://developers.scrunch.com/api-reference/audit-scores/get-site-audit-score /api-reference/openapi.json get /{brand_id}/audit-scores/site The brand's site-level AI-visibility score — retrievability and citability rolled up across the whole site (the same numbers the Site Optimization header shows), when it was scored (`generated_at`), the previous run's score for a delta, and `headroom` (the projected site score per metric if every surfaced opportunity is fixed). `null` when the brand has no audit yet. # List Page Audit Scores Source: https://developers.scrunch.com/api-reference/audit-scores/list-page-audit-scores /api-reference/openapi.json get /{brand_id}/audit-scores/pages The latest AI-visibility score per page for a brand — retrievability and citability, each page's `url`, when it was scored (`generated_at`), its headroom (open work by severity), and the sitemap page it maps to (`mapped_page_id`, null when unmatched). Page through the whole brand with `limit` (max 1000) and `offset`. Ordered by page `url` (stable for pagination), not by score. # Audit Scores API: Retrievability and citability by page Source: https://developers.scrunch.com/api-reference/audit-scores/overview Read a brand's AI-visibility scores — retrievability and citability — rolled up for the whole site and broken out per page, with the headroom left on each. ## Overview The Audit Scores API returns the AI-visibility scores Scrunch computes from its most recent site audit: **retrievability** (can an AI crawler reach and parse the page) and **citability** (once reached, is the page worth quoting). These are the same numbers the Site Optimization header shows in the dashboard. Two endpoints cover two questions: how is the site doing overall, and which pages are holding it back. *** ## Endpoints | Method | Path | Purpose | | - | - | - | | GET | `/{brand_id}/audit-scores/site` | The site-level score, rolled up across every audited page. | | GET | `/{brand_id}/audit-scores/pages` | The latest score per page, with each page's headroom. | Both require a bearer token with the `query` scope. See [Authentication](/getting-started/authentication). *** ## Example request ```bash theme={null} curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \ "https://api.scrunchai.com/v1/1234/audit-scores/site" ``` ```bash theme={null} curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \ "https://api.scrunchai.com/v1/1234/audit-scores/pages?limit=200&offset=0" ``` *** ## Reading the fields Two things are easy to misread. > [!WARNING] > > **A `null` site score is not an error.** `GET /audit-scores/site` returns `null` when the brand has no finished audit yet — a new brand, or one whose first crawl is still running. Treat it as "not scored yet" rather than "scored zero", and check for it before charting. **The page list is ordered by `url`, not by score.** That is deliberate: a stable order is what makes `limit`/`offset` paging safe across requests, because a score that changes mid-page would otherwise shuffle rows between pages and cause you to skip or repeat one. Sort client-side if you want the worst pages first. `limit` accepts up to 1000. Page through the whole brand with `offset`; each page carries its `url`, its scores, and `generated_at` for when it was last scored. # Bulk Render Optimized Pages Source: https://developers.scrunch.com/api-reference/axp-render/bulk-render-optimized-pages /api-reference/openapi.json post /orchestration/render-bulk/{brand_id}/sites/{site_id} Queue render jobs for a list of paths on a registered AXP site. Each path is fetched, sanitized, and persisted as an AXP optimized page asynchronously, so the endpoint returns immediately with one job entry per input path. Paths are normalized (trimmed and given a leading slash) and deduplicated before queueing. A path that already has an in-flight job on the same site coalesces onto that job, so the same batch can be retried safely. Inputs are capped at 100 paths per call. > [!WARNING] > > This API is deprecated. Existing integrations keep working, but don't build new ones on it. # Unpublish Optimized Pages Source: https://developers.scrunch.com/api-reference/axp-render/unpublish-optimized-pages /api-reference/openapi.json post /orchestration/unpublish/{brand_id}/sites/{site_id} Removes the curated (Adaptive) content at each path, including edits made in the Agent Pages content editor. It does not remove the Agent Page generated from the live site, which keeps serving at that path. A path with no curated content returns `not_found`; sites below AXP engine 2.1.0 are refused with 409. To remove an Agent Page, see the Force Refresh overview. Stop serving optimized content for a list of paths on a registered AXP site. Each path is removed from the edge and its row is terminally retired, so no automated writer (re-stage, redeploy, rollback, or render job) republishes it. The endpoint is idempotent and returns one outcome per requested path. Designed for compliance-driven takedowns that must land faster than the weekly optimization cadence — for example when a regulated page has been pulled from your origin and must stop being served from Scrunch's edge immediately. Requires the target site to be on AXP engine version 2.1.0 or later. On earlier engines a page is only unpublished by the next version deploy, so a request against a 2.0.0 site is refused with a 409 before any row is changed. A human with `brand:update` can still bring a taken-down page back live from the Scrunch dashboard; the terminal state only binds automated writers. # AXP Render API: Queue Optimized Page Renders Source: https://developers.scrunch.com/api-reference/axp/overview Queue asynchronous render jobs that fetch, sanitize, and persist pages on your AXP site so optimized content is ready to deploy from one API call. > [!WARNING] > > This API is deprecated. Existing integrations keep working, but don't build new ones on it. ## Overview The AXP Render API queues asynchronous render jobs for paths on a registered AXP site. Each job fetches the live page from your origin, strips noise (scripts, styles, inline event handlers, base64 images), and persists the cleaned HTML as an optimized page that you can then edit, version, and deploy from the Scrunch dashboard. Use it to seed an AXP site with content programmatically — for example, after a sitemap import or when onboarding a new domain — without clicking through **Add Content** for each path. Renders run in the background. The endpoint responds as soon as jobs are queued; you can correlate the returned `job_id` with the page that appears in the AXP content list once the job completes. *** ## When to use the AXP Render API Use this API when you need to: * Bulk-seed an AXP site with optimized pages for a known list of paths. * Re-render an archived path to reactivate it as an Active page. * Refresh stale renders after a marketing-site redeploy, on a schedule. For interactive, one-off renders, use **Add Content → Render from site** in the Scrunch dashboard. For audit-then-optimize-then-deploy workflows, use the [Optimize and Deploy API](/api-reference/optimize-deploy) instead. To take an already-optimized page off the edge, use the [AXP Unpublish API](/api-reference/axp/unpublish). *** ## Endpoint | Method | Path | Purpose | | - | - | - | | POST | `/v2/orchestration/render-bulk/{brand_id}/sites/{site_id}` | Queue render jobs for a list of paths on a site. | The endpoint requires a bearer token with the `configure` scope. See [Authentication](/getting-started/authentication). *** ## Request | Field | Type | Required | Description | | - | - | - | - | | `paths` | `string[]` | Yes | Paths to render. Each entry is trimmed and given a leading slash if missing. Capped at **100 paths** per call. | ### Path normalization and deduplication Before queueing, the API normalizes each path: * Surrounding whitespace is stripped. * A leading `/` is added when missing. * Duplicates after normalization are dropped, preserving input order. So `["/blog", "blog", " /blog "]` queues a single job for `/blog`. ### Coalescing in-flight jobs If a path already has a `pending` or `running` job on the same site, the request returns the existing `job_id` instead of queueing a new one. This makes the endpoint safe to retry with the same batch — you won't end up with duplicate renders or duplicate optimized pages. *** ## Response The response is an array of items, one per unique path: | Field | Type | Description | | - | - | - | | `path` | `string` | The normalized path the job was queued for. | | `job_id` | `integer` | Identifier of the render job. Use it for correlation in logs. | | `status` | `string` | Job status at response time. `pending` means a fresh job was queued; `running` means the call coalesced onto an existing job. | Job status values: `pending`, `running`, `succeeded`, `failed`, `cancelled`. *** ## Example: queue renders ```bash theme={null} curl -X POST \ "https://api.scrunchai.com/v2/orchestration/render-bulk/1234/sites/01JEXAMPLE00000000000000" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "paths": [ "/", "/pricing", "/blog/launch-announcement" ] }' ``` **Response:** ```json theme={null} [ { "path": "/", "job_id": 1842, "status": "pending" }, { "path": "/pricing", "job_id": 1843, "status": "pending" }, { "path": "/blog/launch-announcement", "job_id": 1801, "status": "running" } ] ``` In this response the first two paths were freshly queued, and `/blog/launch-announcement` coalesced onto an in-flight job (`1801`) from an earlier call. *** ## Errors | Status | When | | - | - | | `400` | The site is not active for AXP, or has no domain configured. | | `404` | No site with the supplied ULID exists for the brand. | | `422` | The request body failed validation (empty `paths`, more than 100 entries, path longer than 2048 chars). | | `502` | Jobs were persisted but at least one dispatch to the background worker failed. The affected jobs are marked `failed`; retry those paths. | *** ## Limits and behavior * Maximum **100 paths** per request. Split larger batches into multiple calls. * Each path must be 1–2048 characters after normalization. * The target site must have `axp_status` set to `active` and a configured domain. * Re-rendering a path that exists as an archived page reactivates it as **Active** and logs a `CONTENT_CREATED` event. * Pages rendered through this API show up in the AXP content list with the same statuses as renders started from the dashboard. *** ## Best practices * Poll the dashboard or correlate job IDs from your logs to confirm completion — `succeeded` jobs produce an optimized page you can deploy. * Retry idempotently. Because in-flight jobs coalesce, the same batch can be sent again after a network error without creating duplicate work. * Pair with the [Sitemap API](/api-reference/sitemap/overview) to source the path list. Filter by `is_priority=true` to seed AXP with your most important pages first. # AXP Unpublish API: Take Optimized Pages Off the Edge Source: https://developers.scrunch.com/api-reference/axp/unpublish Remove curated (Adaptive) AXP pages from the edge on demand and retire them so no re-stage, redeploy, or rollback brings them back. Not for Agent Pages. ## Overview > [!WARNING] > > This API removes the **curated (Adaptive) content** at a path, including edits made in the Agent Pages content editor. It does not remove the Agent Page that Scrunch generates from your live site: after an unpublish, agents receive that version instead. To remove the Agent Page, use [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview). A path with no curated content returns `not_found`, and on sites below AXP engine 2.1.0 the whole request is refused with `409`. To remove, refresh, or add an Agent Page, see [Which API do I need?](/api-reference/agent-pages/force-refresh-overview#which-api-do-i-need). The AXP Unpublish API takes a list of paths off the edge for a registered AXP site and retires their optimized-page rows in a way that no automated writer will undo. It is designed for compliance-driven takedowns that must land faster than the weekly optimization cadence. Each request runs immediately: for every path, the deterministic edge key is deleted and the row is marked as archived with a terminal `api_takedown` reason. Once a row is in that state, a re-stage, a redeploy of an older version, a rollback, or a render job will leave it retired — the page's content is preserved, but nothing brings it back live automatically. Bringing a taken-down page back live still works from the Scrunch dashboard. The terminal state only binds automated writers; a human with `brand:update` can re-activate the page through **Optimized pages → Edit**, which clears the removal reason. *** ## When to use the AXP Unpublish API Use this API when you need to: * Remove a curated page from the edge immediately, for example after pulling a regulated page from your origin. * Guarantee a removal survives your normal optimization and deploy cycles without a human watching for silent resurrection. * Wire a delete surface from a notify or content-management integration through one shared front door. For interactive removals, use **Optimized pages → Archive** in the Scrunch dashboard. That archive is deliberately reversible: an optimizer re-stage or a redeploy of an older version may bring the page back. Use this API when you need the removal to stick. *** ## Endpoint | Method | Path | Purpose | | - | - | - | | POST | `/v2/orchestration/unpublish/{brand_id}/sites/{site_id}` | Unpublish a list of paths on one AXP site. | The endpoint requires a bearer token with the `configure` scope. See [Authentication](/getting-started/authentication). ### Engine version requirement The endpoint requires the target site to be on **AXP engine version 2.1.0 or later**. On 2.1.0+, a page is served if and only if its deterministic edge key exists, so deleting the key is the unpublish. On earlier engines a page stops being served only when the next version deploy rebuilds the routing manifest without its path. A request against a site below 2.1.0 is refused with a `409` before any row is touched. This is deliberate: retiring the row anyway would return success for a takedown whose serving half lands at an unknown later time. *** ## Request | Field | Type | Required | Description | | - | - | - | - | | `paths` | `string[]` | Yes | Site-relative paths to unpublish. Each entry is trimmed and given a leading slash if missing. Capped at **100 paths** per call. | ### Path normalization and deduplication Before processing, the API normalizes each path: * Surrounding whitespace is stripped. * A leading `/` is added when missing. * Duplicates after normalization are dropped, preserving input order. Case is preserved. `/Home` and `/home` are two separate rows and are processed separately. *** ## Response The response is an object with a `results` array holding one entry per requested path, in the order the paths were sent. | Field | Type | Description | | - | - | - | | `results[].path` | `string` | The normalized path this outcome applies to. | | `results[].outcome` | `string` | What happened to this path. See the table below. | | `results[].detail` | `string \| null` | Human-readable context for outcomes a caller may need to act on. | ### Outcome values | Outcome | Meaning | | - | - | | `unpublished` | The edge key is confirmed gone and the row is terminally retired. | | `already_unpublished` | The page was already down. Reported distinctly so a retry reads as a retry, but it is a success — the page is not being served. | | `not_found` | No curated page at that path on this site, so there is nothing for this API to remove. If the path is served as an Agent Page, that version is still live; remove it with [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview). | | `failed` | The edge did not confirm the delete, so the page may still be served. The row is deliberately left untouched, and the daily reconcile sweep retries the delete. Retry the path once the reconcile has run or contact support if it keeps recurring. | | `skipped` | Another active page owns the same deterministic edge key (for example `/About-Us` and `/about-us` map to one edge object). Deleting the key would take a live page down. Rename one of the paths in the Scrunch dashboard, then retry. | The request itself succeeds — HTTP `200` — as long as it was well-formed and the site is eligible. Failures on individual paths surface as `failed` outcomes in the body so a caller with a 100-path list is not blocked by one bad entry. *** ## Example: unpublish curated pages ```bash theme={null} curl -X POST \ "https://api.scrunchai.com/v2/orchestration/unpublish/1234/sites/01JEXAMPLE00000000000000" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "paths": [ "/promo/2024-rates", "/legal/old-disclosure", "/blog/removed-post" ] }' ``` **Response:** ```json theme={null} { "results": [ { "path": "/promo/2024-rates", "outcome": "unpublished", "detail": null }, { "path": "/legal/old-disclosure", "outcome": "already_unpublished", "detail": null }, { "path": "/blog/removed-post", "outcome": "not_found", "detail": null } ] } ``` *** ## Errors | Status | When | | - | - | | `400` | The site has no CDN platform configured. | | `404` | No site with the supplied ULID exists for the brand. | | `409` | The site's AXP engine is below version 2.1.0, so on-demand unpublish is not supported. No pages are changed. | | `422` | The request body failed validation (empty `paths`, more than 100 entries, empty path, or path longer than 2048 characters). | *** ## Limits and behavior * Maximum **100 paths** per request. Split larger batches into multiple calls. The endpoint is idempotent, so re-sending overlapping batches is harmless. * Each path must be 1–2048 characters after normalization. * The row is committed as retired **before** the edge delete is issued. If the process crashes between the two, the reconcile sweep converges the state by finishing the edge delete on its next run. * A page that was previously archived from the dashboard is upgraded to a terminal takedown on the first `unpublished` outcome. From then on, automated writers stop being able to bring it back. * Lifting a takedown is a human action: edit the page in the Scrunch dashboard and set its status back to **Active**. That clears the terminal state and re-enables the normal reversible archive semantics. *** ## Best practices * **Retry idempotently.** The endpoint is safe to retry after network errors or partial failures; already-taken-down paths report `already_unpublished` and are counted as success. * **Act on `failed` and `skipped` results.** These are the only outcomes a caller usually needs to do something about — retry `failed` after the reconcile sweep has run, and resolve the key collision behind `skipped` before retrying. * **Confirm engine eligibility before wiring a compliance flow.** If your sites are still on AXP 2.0.0, this endpoint will 409 uniformly. Contact your Customer Success representative to migrate a site to 2.1.0. * **Audit through activity log.** Each successful takedown records a `CONTENT_TAKEN_DOWN` activity entry tagged with the API key, so removals can be traced back to the caller. # Configuration API: Manage Brands and Prompts Source: https://developers.scrunch.com/api-reference/configuration/overview Create brands, manage competitors and personas, and configure tracking prompts via the Scrunch Configuration API to automate client onboarding. The Configuration API lets you manage Scrunch brands at scale.\ It is most commonly used by: * Agencies onboarding dozens or hundreds of clients * Enterprise teams automating persona and keyword setup * Internal tools (brand creation, batch updates, auditing) *** ## What you can configure ### Brands * Name, alternative names * Website + alternative websites * Competitors * Personas * Key topics ### Prompts * Text * Stage * Tags * Personas * Platforms ### Sites (read-only) * List a brand's sites and their IDs, with whether each serves Agent Pages and Agent Traffic. Other endpoints take the ID as `{site_id}`. Any API key with access to the brand works; no scope is required. *** ## Example: Create a brand ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/brands" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Spirit Airlines", "website": "https://spirit.com", "description": "Low cost air carrier." }' ``` *** ## Case-sensitive name matching By default, Scrunch matches brand and competitor names against AI responses case-insensitively, so `"spirit airlines"`, `"Spirit Airlines"`, and `"SPIRIT AIRLINES"` all count as mentions. For names that are common words, acronyms, or stylized in a specific case (for example, `NeXT` or `LUSH`), enable case-sensitive matching to avoid false positives. Set `case_sensitive: true` on a brand or competitor to require exact-case matches for `name` and `alternative_names`. The flag defaults to `false` and is available on: * `POST /brands` — on the brand body and on each entry in `competitors[]` * `PATCH /brands/{brand_id}` — on the brand and on each competitor in the replacement list * `POST /brands/{brand_id}/competitors` and `PUT /brands/{brand_id}/competitors/{competitor_id}` * `GET` responses for brands and competitors return the current value ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/brands" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "LUSH", "website": "https://lush.com", "case_sensitive": true, "competitors": [ { "name": "The Body Shop", "case_sensitive": false } ] }' ``` > [!NOTE] > > Changing `case_sensitive` on an existing brand triggers a re-evaluation of historical responses against the new matching rule. ## Domain uniqueness across brand and competitors Each domain can only be classified one way within a brand — either as the brand's own or as one specific competitor's. This keeps citation owner classification (`brand` / `competitor` / `other`) deterministic. Scrunch normalizes every configured URL by stripping the scheme, `www.`, query, fragment, and trailing slash, and lowercasing it. The brand's primary `website` is compared by domain only, while `alternative_websites` and competitor `websites` keep their path — so `example.com/a` and `example.com/b` on two different owners do not conflict. If a write would assign the same normalized domain to two different owners (for example, the brand's `website` and a competitor's `websites`, or two competitors), the request is rejected with HTTP `409` and a `detail` describing where the domain is already used. The check applies to: * `POST /brands` and `PATCH /brands/{brand_id}` (brand `website`, `alternative_websites`, and the replacement `competitors[]`) * `POST /brands/{brand_id}/competitors` and `PUT /brands/{brand_id}/competitors/{competitor_id}` Only newly introduced conflicts are blocked, so unrelated edits to a brand that already contains a legacy collision still save. To move a domain between owners, remove it from the current owner in the same request that adds it to the new one. ```json theme={null} { "detail": "example.com is already configured as the competitor 'Acme' for this brand. A domain can only be classified one way (brand vs. competitor)." } ``` ## Asynchronous website validation After a write commits, Scrunch checks each new or changed website URL in the background. The checks confirm that the hostname resolves to a public address and that the page responds over HTTP. These checks are advisory. They never delay, reject, or roll back a structurally valid save, so your API response is unaffected. Background checks run for URLs submitted through: * `POST /brands` and `PATCH /brands/{brand_id}` (brand `website`, `alternative_websites`, and competitor `websites` in the replacement list) * `POST /brands/{brand_id}/competitors` and `PUT /brands/{brand_id}/competitors/{competitor_id}` (`websites`) Only new or changed URLs are checked. Malformed URLs are still rejected synchronously at write time, before the background checks run. If any check fails, Scrunch creates one aggregated notification in the dashboard notification bell for the user who owns the API key. Other users of the brand are not notified. Clicking the notification opens **Configure → Brand Entities** with a banner listing each affected URL and its result, such as page not found or host did not resolve. If a check could not be completed, the notification says so explicitly. An incomplete check does not mean the URL is invalid. Successful checks are silent. To clear a warning, correct the URL with another write; the updated URL is checked again. Responses that only block automated access (`401`, `403`, or `429`) do not create a warning. Sites often return these codes to automated clients while remaining reachable in a browser, so they do not indicate that the URL is invalid. If a run contains both blocked-access results and other failures, the notification reports only the other failures. ```bash theme={null} # The save succeeds immediately even if the website is unreachable. # A warning notification appears in the dashboard afterward. curl -X POST "https://api.scrunchai.com/v1/brands" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Spirit Airlines", "website": "https://spiritt-typo.com" }' ``` > [!NOTE] > > URL-validation warnings are independent of brand-performance notification preferences and cannot be disabled by those settings. ## Alternative names limit Each brand and competitor accepts up to **100 entries** in `alternative_names`. Submitting more returns a `422 Unprocessable Entity` with the message: ``` alternative_names cannot exceed 100 entries (got N); remove some before saving ``` The cap is enforced on every write endpoint that accepts `alternative_names`, including: * `POST /v1/brands` and `PATCH /v1/brands/{brand_id}` (brand body and each competitor) * `POST /v1/brands/{brand_id}/competitors` and `PUT /v1/brands/{brand_id}/competitors/{competitor_id}` If you previously sent more than 100 aliases, the collection layer silently kept only the 100 shortest. Trim your list before retrying so you control which aliases are retained. ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/brands" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Spirit Airlines", "website": "https://spirit.com", "description": "Low cost air carrier.", "alternative_names": ["Spirit", "Spirit Air", "NK"] }' ``` ## Excluded names Use `excluded_names` to list phrases that should never count as a mention of a brand or competitor, even when the phrase contains a configured name as a word. This lets a brand named `Caliber` match `Caliber Collision` while ignoring unrelated entities like `Caliber Car Wash` or `Caliber Fitness`. Scrunch blanks every occurrence of each excluded phrase that matches under the same rules as brand names (see [Names in Japanese, Chinese, Korean, and Thai text](#names-in-japanese-chinese-korean-and-thai-text)) before searching the response for this entity's names. An excluded phrase that is a word inside one of the entity's own names is left alone wherever it appears as part of that name. For example, a brand named `Close Brothers` with the exclusion `Close` still matches `Close Brothers`, while a standalone `Close` is blanked. Position and other span-based metrics are unaffected because masked spans are replaced with equal-length whitespace. Historical responses are re-evaluated when `excluded_names` changes, so metrics update without a manual backfill. `excluded_names` is a list of strings and is available on: * `POST /v1/brands` — on the brand body and on each entry in `competitors[]` * `PATCH /v1/brands/{brand_id}` — on the brand and on each competitor in the replacement list * `POST /v1/brands/{brand_id}/competitors` and `PUT /v1/brands/{brand_id}/competitors/{competitor_id}` * `GET` responses for brands and competitors return the current value ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/brands" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Caliber", "website": "https://caliber.com", "excluded_names": ["Caliber Car Wash", "Caliber Fitness", "Caliber Armor"] }' ``` Each brand and competitor accepts up to **100 entries** in `excluded_names`. Submitting more returns a `422 Unprocessable Entity` with: ``` excluded_names cannot exceed 100 entries (got N); remove some before saving ``` Scrunch rejects an exclusion that equals the entity's own `name` or any of its `alternative_names`, since either would remove every mention of the entity. Remove the alternative name instead of excluding it. The check runs after Scrunch normalizes punctuation, so `Caliber.` and `Caliber` are treated as the same phrase. ## Names in Japanese, Chinese, Korean, and Thai text Scrunch normally counts a name only when it stands as a separate word, so `Spirit` does not match inside `Spirited`. Japanese, Chinese, and Thai do not put spaces between words, and Korean attaches particles directly to names. Scrunch adjusts the word-boundary rule for these scripts so mentions are still counted: * **Names in these scripts** match even when surrounding text runs directly into them, so `第一生命` matches in `第一生命の保険`. * **Korean names** must still start at a word boundary but can be followed directly by a particle, so `삼성` matches in `삼성은` but `기아` does not match inside `기압`. * **Latin names next to these scripts** match when the adjacent character is from one of these scripts, so `Lenovo` matches in `LenovoノートPC`. Latin names in Latin text match exactly as before. * **One-character names** still require a word boundary on both sides. Japanese voicing marks are significant, so `ダブ` does not match `タブレット`. Accents on Latin letters are still ignored, so `Café` matches `cafe`. Because names in these scripts match without a boundary, short names can match inside longer, unrelated words. For example, `モス` matches inside `モスクワ` (Moscow). Add the longer words to `excluded_names` to stop them counting as mentions. The same rules apply to `name`, `alternative_names`, `excluded_names`, and the prompt `branded` flag. ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/brands" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "モスバーガー", "website": "https://www.mos.jp", "alternative_names": ["モス"], "excluded_names": ["モスクワ"] }' ``` ## Excluded websites Use `excluded_websites` to list sites whose citations should not count as owned by the brand or any of its competitors. This is useful when a subdomain or path under a configured website belongs to someone else. For example, a brand with `website` set to `example.com` can exclude `advisors.example.com` when that subdomain is a separate business. Scrunch reclassifies excluded citations as third party (`other`). It does not remove them, so total citation counts stay the same and only the owner split changes. The most specific match wins, so an excluded subdomain or path overrides its parent domain. The change applies to all historical citations without re-evaluating stored responses. Exclusions are brand-wide. An entry set on a competitor applies to the whole brand, not only to that competitor. Exclusions on an archived competitor stop applying. `excluded_websites` is a list of strings and is available on: * `POST /v1/brands`: on the brand body and on each entry in `competitors[]` * `PATCH /v1/brands/{brand_id}`: on the brand and on each competitor in the replacement list * `POST /v1/brands/{brand_id}/competitors` and `PUT /v1/brands/{brand_id}/competitors/{competitor_id}` * `GET` responses for brands and competitors, which return the stored value On `PATCH /v1/brands/{brand_id}` competitor entries and on `PUT /v1/brands/{brand_id}/competitors/{competitor_id}`, omitting `excluded_websites` leaves the stored list unchanged. Send `[]` to clear it. ```bash theme={null} curl -X PATCH "https://api.scrunchai.com/v1/brands/1234" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "excluded_websites": ["advisors.example.com", "example.com/partners"] }' ``` ### Normalization and limits Scrunch normalizes each entry before storing it. It strips the scheme, `www.`, port, query, fragment, and trailing slash, then lowercases the result. A locale-only path collapses to the domain, so `example.com/en-us` is stored as `example.com`. For example, `HTTPS://WWW.Partners.Example.com/` is stored as `partners.example.com`. `GET` responses return the normalized values. * Duplicate entries are removed. * Each brand and competitor accepts up to **100 entries**. Submitting more returns a `422 Unprocessable Entity` with `excluded_websites cannot exceed 100 entries (got N); remove some before saving`. * Entries with credentials (`@`) or wildcards (`*`) return `422`. An entry already covers its subdomains, so wildcards are not needed. ### Conflicts Scrunch rejects a write with HTTP `409` when an exclusion collides with an owned website. The `detail` explains what would break. A write is rejected when an exclusion matches: * The brand's `website` or `alternative_websites` * Any competitor's `websites`, including competitors other than the one the exclusion is set on * A sub-brand website, a subdomain or path under a sub-brand website, or a parent of a sub-brand website Adding a website that is already excluded is also rejected until you remove the exclusion. ```json theme={null} { "detail": "example.com is configured as this brand's own website. Excluding it would reclassify every citation on it as third party." } ``` Excluding a subdomain or path under a brand or competitor website is allowed. ## Example: Add a prompt ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/1234/prompts" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "text": "What are the best budget airlines?", "tags": ["budget"], "platforms": ["chatgpt", "perplexity"] }' ``` ## Tag name limit Each entry in a prompt's `tags` array is limited to **64 characters**. Submitting a longer tag name to `POST /{brand_id}/prompts` returns a `400 Bad Request` with a structured `detail` object: ```json theme={null} { "detail": { "code": "tag_name_too_long", "tag": "budget airlines, low cost carriers, cheap flights, best value airlines", "max_length": 64, "message": "Tag 'budget airlines, low cost carriers, cheap flights, best value …' is longer than 64 characters. Separate multiple tags with commas." } } ``` The check runs before any tag is created, so a request with one over-long name creates no tags at all. Over-long names usually come from joining several tags into a single string. Send each tag as its own array entry instead: ```json theme={null} { "tags": ["budget", "low cost", "best value"] } ``` Tag names at exactly 64 characters are accepted. The limit applies only when creating tags; referencing existing tags is unaffected. ## Duplicate prompt text `POST /{brand_id}/prompts` checks the new text against the brand's existing prompts. The outcome depends on the existing prompt's status: * **Active duplicate** — returns `400 Bad Request` with the message `Prompt already exists`. * **Paused duplicate** — returns `400 Bad Request` with a structured `detail` object identifying the paused prompt, so you can resume it instead of creating a copy: ```json theme={null} { "detail": { "type": "paused_duplicate", "message": "A paused prompt with this text already exists", "prompt_id": 5678 } } ``` * **Archived duplicate** — reactivates the archived prompt instead of returning an error. ## Listing prompts `GET /{brand_id}/prompts` returns active prompts by default. Pass the `status` query parameter to include paused or archived prompts: | Value | Returns | | - | - | | `active` (default) | Currently tracked prompts | | `paused` | Prompts whose collection is paused; their history stays visible | | `archived` | Soft-deleted prompts only | | `all` | Active, paused, and archived prompts | Any other value returns a `422 Unprocessable Entity` rather than an empty list. ```bash theme={null} # Only paused prompts curl "https://api.scrunchai.com/v1/$BRAND_ID/prompts?status=paused" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" # All prompts including paused and archived ones curl "https://api.scrunchai.com/v1/$BRAND_ID/prompts?status=all" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` Each prompt in the response includes: * `branded` — `true` if the prompt mentions the brand * `favorite` — `true` if marked as a favorite in the dashboard * `status` — `active`, `paused`, or `archived` For paused prompts, `platforms` and `variants` reflect the prompt's active variants. Pausing never changes them, so they show what a resume would collect again. `GET /{brand_id}/prompts/{prompt_id}` returns archived prompts as well, so check the `status` field if you only want active ones. *** ## Pausing and resuming prompts `PATCH /{brand_id}/prompts/{prompt_id}` moves a prompt between `active` and `paused`. It requires the `configure` scope, and `status` is the only field the body accepts. ```bash theme={null} # Pause a prompt curl -X PATCH "https://api.scrunchai.com/v1/$BRAND_ID/prompts/$PROMPT_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "paused" }' # Resume it curl -X PATCH "https://api.scrunchai.com/v1/$BRAND_ID/prompts/$PROMPT_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "active" }' ``` **Pausing** stops collection and releases the prompt's variants from the organization's prompt pool. The prompt keeps its configuration and all of its collected history, and stays readable through `GET /{brand_id}/prompts?status=paused`. **Resuming** restores the exact deployment the prompt had when it was paused. Scrunch re-checks the prompt pool first, so a resume can return `429` with a `quota_exceeded` error when the organization no longer has room for the prompt's variants. Both transitions are idempotent: a prompt already in the requested status returns `200` with the prompt, unchanged. `archived` is not accepted as a target status; archive a prompt with `DELETE /{brand_id}/prompts/{prompt_id}` instead. A transition the prompt's current state does not allow returns `409` with a `detail.type` naming the reason: | `detail.type` | Meaning | | - | - | | `is_archived` | Archived prompts cannot be paused or resumed | | `persona_archived` | The prompt's persona is archived; `detail.blocking_persona_ids` lists the personas to restore or reassign before resuming | | `active_duplicate` | An active prompt with the same text, persona, and country already exists | | `no_active_variants` | The prompt has no active variants, so resuming it would collect nothing | A `503` with `detail.type` of `pause_failed` or `resume_failed` means the transition did not complete. Retry the request. *** ## Archiving a persona pauses its prompts Archiving a persona pauses its active custom prompts instead of archiving them. Collection and billing stop, but the prompts' collected history stays visible on the Responses and Query APIs. The paused prompts appear under `status=paused` in the prompt listing. This applies to every path that archives a persona: * `DELETE /brands/{brand_id}/personas/{persona_id}` * `PATCH /brands/{brand_id}` when the `personas` replace-list omits an existing persona Prompts that reference the persona only through variants keep collecting on their remaining active variants; a prompt left with no active variant is paused. Already paused, archived, and industry prompts are not affected. To resume the paused prompts, restore the persona or reassign the prompts to another persona, then resume them. *** ## Reusing an archived persona name When you `PATCH /brands/{brand_id}` with personas, the list represents the full desired state: existing personas not included are archived. If you later submit a persona without an `id` and the `name` matches a previously archived persona on the same brand, Scrunch reactivates the archived record instead of failing on the unique-name constraint. Its `status` returns to `active` and the `description` is replaced with the value you provide. ```bash theme={null} curl -X PATCH "https://api.scrunchai.com/v1/brands/$BRAND_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "personas": [ { "name": "Budget Traveler", "description": "Price-sensitive consumer" } ] }' ``` If `Budget Traveler` was previously archived on this brand, the call reactivates that persona and updates its description. To update an existing active persona instead, include its `id`. *** ## Personas can't name the brand Scrunch sends a persona with every prompt it collects. If a persona's name or description mentions the brand, it turns non-branded prompts into branded ones and inflates visibility. Scrunch refuses persona text that names the brand on every endpoint that writes personas: * `POST /brands` (the `personas` array) * `PATCH /brands/{brand_id}` (the `personas` replace-list) * `POST /brands/{brand_id}/personas` * `PUT /brands/{brand_id}/personas/{persona_id}` The check uses the same rules as mention matching. It looks for the brand's `name` and `alternative_names`, respects `case_sensitive`, and ignores phrases listed in `excluded_names`. Only text you're writing is checked. A `PATCH` that resends an existing persona unchanged, or a `PUT` that keeps the stored name or description, isn't refused for that text. A refused request returns `400 Bad Request` with the error code `PERSONA_NAMES_BRAND`. Nothing is saved. On `POST /brands`, the brand isn't created. ```json theme={null} { "detail": { "error_code": "PERSONA_NAMES_BRAND", "message": "Persona text names the brand: \"Spirit fan\" (Spirit). Personas are sent with every prompt, so the brand name would inflate visibility on non-branded prompts. Remove it and resend.", "params": { "count": 1, "personas": ["Spirit fan"], "names": ["Spirit"], "fields": ["name"] } } } ``` | Field | Description | | - | - | | `count` | Number of refused personas | | `personas` | Names of the refused personas | | `names` | Brand names that matched, including alternative names | | `fields` | Persona fields that contained a match: `name`, `description`, or both | To recover, remove the matched names from the listed personas' fields and resend the request. If the brand name is an everyday word that appears in persona text without referring to the brand, enable `case_sensitive` or add the phrase to the brand's `excluded_names`. *** ## Persona limits when creating a brand `POST /brands` accepts an optional `personas` array. Each plan caps how many personas you can attach to a single brand. If the array is longer than your plan allows, the request is rejected before the brand is created — no partial brand is saved. When the limit is exceeded, the API returns `429 Too Many Requests` with a `quota_exceeded` error: ```json theme={null} { "detail": { "error": "quota_exceeded", "feature_key": "brand.personas.count", "limit": 3, "used": 5, "message": "This plan allows up to 3 personas per brand; received 5." } } ``` To recover, trim the `personas` array to `limit` entries or fewer and retry the request. To find your plan's limit, inspect the `limit` field in the error response or contact your account team. > [!TIP] > > Personas can also be added or replaced after a brand is created via `POST /brands/{brand_id}/personas` and `PATCH /brands/{brand_id}`. The cap is currently enforced only at brand creation. *** ### Notes > [!NOTE] > > To update prompt text, delete the old prompt and create a new one. Only tags and platforms can be updated in-place. > [card] [See all configuration endpoints](/api-reference) > > Explore the API reference → # Get AI Crawl Readiness Source: https://developers.scrunch.com/api-reference/crawl-readiness/get-ai-crawl-readiness /api-reference/openapi.json get /{brand_id}/crawl-readiness Whether AI crawlers can reach one of the brand's domains, based on the brand's most recent finished crawl of it. These are the same signals the AI Access card shows in the Scrunch dashboard. Pass `domain` to choose which of the brand's domains to describe; omit it for the primary website. The response is `null` when the brand owns the domain but no crawl of it has finished yet; requesting a domain the brand does not own returns `404`. Reading the fields: - `robots_txt_present`: whether a robots.txt was found. **False means permissive**, not blocked: with no robots.txt, crawlers are allowed by default. - `is_blocking_bots`: the site turns crawlers away, derived from the share of pages that answered HTTP 403 across the whole crawl. This is a server-level verdict and is unrelated to `blocked_pages`, which is about robots.txt. - `is_spa`: most pages render client-side, so a crawler that does not run JavaScript reads little or nothing. - `blocked_pages`: pages robots.txt blocks, with the AI assistant families blocked from each. **This is a sample, not a complete list**: only the 50 shallowest pages of the crawl are checked. `pages_truncated` is true when the crawl held more than that, so an empty or short list does not mean nothing else on the site is blocked. # Crawl Readiness API: Check AI Crawler Access to a Site Source: https://developers.scrunch.com/api-reference/crawl-readiness/overview Read whether AI crawlers can reach your brand's domains: robots.txt status, bot blocking, client-side rendering, and which pages robots.txt blocks. ## Overview The Crawl Readiness API reports whether AI crawlers can reach one of your brand's domains, based on the brand's most recent finished crawl of that domain. It returns the same signals the AI Access card shows in the Scrunch dashboard. Use it to check from your own backend whether a customer's site is reachable by AI crawlers before investing in AI visibility work, or to surface readiness inside a partner integration. The endpoint is read-only. Nothing about how readiness is computed changes when you call it. *** ## What the Crawl Readiness API includes * Whether a `robots.txt` file was found for the domain * Whether the site turns crawlers away at the server level (based on HTTP 403 rates across the crawl) * Whether the site renders mostly client-side, which limits what non-JavaScript crawlers can read * A sample of pages that `robots.txt` blocks, with the AI assistant families (OpenAI, Meta, Perplexity, Gemini, Claude) blocked from each *** ## When to use the Crawl Readiness API Use the Crawl Readiness API when you need to: * Check whether a brand's domain is reachable by AI crawlers from a partner backend or CMS integration * Flag robots.txt rules that block AI assistants from specific pages * Detect sites that render client-side and may appear empty to non-JavaScript crawlers For a detailed per-page audit score with content-quality checks, use the [Site Audit API](/api-reference/site-audit/overview) instead. To see which AI bots actually visit your pages, use the [Agent Traffic API](/api-reference/agent-traffic/overview). *** ## Endpoint | Method | Path | Purpose | | - | - | - | | GET | `/{brand_id}/crawl-readiness` | Crawl readiness signals for one of the brand's domains. | The endpoint requires a bearer token with the `query` scope. See [Authentication](/getting-started/authentication). Pass the optional `domain` query parameter to choose which of the brand's domains to describe. Omit it for the brand's primary website. *** ## Example: check the primary website ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/crawl-readiness" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` **Response:** ```json theme={null} { "domain": "example.com", "robots_txt_present": true, "is_spa": false, "is_blocking_bots": false, "blocked_pages": [ { "path": "/internal/pricing-drafts", "url": "https://example.com/internal/pricing-drafts", "blocked_by": ["OpenAI", "Perplexity"] } ], "pages_truncated": false } ``` To describe a different domain the brand owns: ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/crawl-readiness?domain=shop.example.com" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` *** ## Reading the response Two fields are easy to misread: * `robots_txt_present: false` means **permissive**, not blocked. With no robots.txt, crawlers are allowed by default. * `blocked_pages` is a **sample, not a complete list**. Only the 50 shallowest pages of the crawl are checked against robots.txt. When `pages_truncated` is `true`, the crawl held more pages than that, so an empty or short list does not prove nothing else on the site is blocked. The remaining fields: | Field | Type | Description | | - | - | - | | `domain` | String | The domain the signals describe. | | `is_blocking_bots` | Boolean | The site turns crawlers away, derived from the share of pages that answered HTTP 403 across the whole crawl. This is a server-level verdict and is unrelated to `blocked_pages`, which is about robots.txt. | | `is_spa` | Boolean | Most pages render client-side, so a crawler that does not run JavaScript reads little or nothing. | | `blocked_pages[].blocked_by` | Array of strings | The AI assistant families robots.txt blocks from that page. Always non-empty for a listed page. | *** ## Limits and behavior * The response is `null` when the brand owns the requested domain but no crawl of it has finished yet. * Requesting a domain the brand does not own returns `404`. An unknown `brand_id` also returns `404`. * Signals come from the brand's most recent finished crawl of the domain, not a live probe. * Pass `domain` as a bare hostname such as `shop.example.com`. A value with a path or port may not match any of the brand's domains and returns `404`. # Create Brand Source: https://developers.scrunch.com/api-reference/create-brand /api-reference/openapi.json post /brands Create a new brand # Create Collection Request Source: https://developers.scrunch.com/api-reference/create-collection-request /api-reference/openapi.json post /{brand_id}/collections Triggers on-demand collection for a prompt across the specified AI platforms. Each platform will be queried and the response evaluated independently. Requires the `configure` scope. The prompt must already exist and have active variants for the requested platforms. # Create Competitor Source: https://developers.scrunch.com/api-reference/create-competitor /api-reference/openapi.json post /brands/{brand_id}/competitors Create a new competitor # Create Page Audits Source: https://developers.scrunch.com/api-reference/create-page-audits /api-reference/openapi.json post /{brand_id}/page-audits Create one or more page audits > [!WARNING] > > The Site Audit API is deprecated. Existing integrations keep working, but don't build new ones on it. # Create Persona Source: https://developers.scrunch.com/api-reference/create-persona /api-reference/openapi.json post /brands/{brand_id}/personas Create a new persona # Create Prompt Source: https://developers.scrunch.com/api-reference/create-prompt /api-reference/openapi.json post /{brand_id}/prompts Creates a new prompt with variants for the specified platforms. Requires the `configure` scope. **Behavior:** - `stage` is optional. If omitted, the journey stage is auto-classified against your brand's active stages using an LLM. - If `stage` is provided, it must match one of your brand's active stages (case-sensitive display name). An unknown value returns `400`. An explicit stage is treated as a manual assertion and won't be overwritten by later re-classification. - Creates variants for each specified platform. - Reactivates an archived prompt if a duplicate exists. A duplicate of a paused prompt is not reactivated; it returns `400` with `type=paused_duplicate` and the paused `prompt_id`. - Dispatches collection events to begin tracking. # Get Competitor Source: https://developers.scrunch.com/api-reference/get-competitor /api-reference/openapi.json get /brands/{brand_id}/competitors/{competitor_id} Get a competitor by ID # Get Page Audit Source: https://developers.scrunch.com/api-reference/get-page-audit /api-reference/openapi.json get /{brand_id}/page-audits/{page_audit_id} Get a specific page audit by ID > [!WARNING] > > The Site Audit API is deprecated. Existing integrations keep working, but don't build new ones on it. # Get Persona Source: https://developers.scrunch.com/api-reference/get-persona /api-reference/openapi.json get /brands/{brand_id}/personas/{persona_id} Get a persona by ID # Scrunch REST API Directory and Authentication Source: https://developers.scrunch.com/api-reference/introduction Find the right Scrunch REST API for your task, see which key scope each one needs, and authenticate every request with an API key as a Bearer token. The Scrunch REST API gives you the same data and configuration as the Scrunch dashboard. Each API has an overview page, then its endpoints. Use this page to find the right one. [Playground →](/api-reference/query?playground=open) ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_api-ref_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=e73c5bf47dc95e0cf30ad8e4c8c85e58) > [!TIP] > > Working in Claude, ChatGPT, or another AI assistant? The Scrunch MCP server covers most of these endpoints without any code. See the [MCP setup guide](/mcp/setup). ## Authentication Every endpoint takes an API key as a Bearer token. Organization admins create keys by clicking the **organization name** in the top-left of the Scrunch dashboard and choosing **API Keys**. ```bash theme={null} export SCRUNCH_API_TOKEN="your-key" curl -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ https://api.scrunchai.com/v1/brands ``` The base URL is `https://api.scrunchai.com/v1`. The few endpoints that use a different host or version say so on their own page. ### API scopes Each key carries one or more **scopes** and is limited to either specific brands or all brands: | Scope | Grants | | - | - | | Query | Reads: metrics, responses, signals, scores, recommendations, and account status, plus keyword volume estimates (starting a keyword list uses the brand's weekly lookups). | | Configure | Changes to brands, competitors, personas, and prompts, plus collection and curated-page (AXP) unpublish requests. | | Create Brand | Creating new brands. | | Optimize | Agent Pages Force Refresh, Unpublish and Publish, and applying Site Optimization changes. | Each API's overview page lists the exact scope its endpoints need. For plan requirements, key rotation, and troubleshooting, see [Provision an API key](/getting-started/authentication). > [!NOTE] > > Create brands with an all-brands key (leave brands unselected when configuring). A key limited to specific brands can create a brand that it then can't read, update, or archive. > [!TIP] > > Calling the API from an AI agent? Install the REST-only `api-*` [Agent Skills](/mcp/skills/overview). They teach your agent these endpoints, the scopes each one needs, and the behavior the schema doesn't document. They use the same `SCRUNCH_API_TOKEN`. ## Find the right API | I want to… | Go to | | - | - | | Pull presence, position, sentiment, or citation metrics for dashboards and reports | [Query API](/api-reference/query/overview) | | Run multi-metric queries with thresholds or period-over-period comparison | [Structured Query](/api-reference/query/structured-query) | | Read the full text and citations of individual AI answers | [Responses API](/api-reference/responses/overview) | | Get alerted when a visibility metric moves | [Signals API](/api-reference/signals/overview) | | See which AI bots crawl my site, or send bot traffic from my own CDN | [Agent Traffic API](/api-reference/agent-traffic/overview) | | Push AI referral traffic from Adobe Analytics or another tool | [AI Referrals API](/api-reference/ai-referrals/overview) | | Estimate weekly AI prompt volume for a list of keywords | [Keyword Volume API](/api-reference/keyword-volume/overview) | | Collect fresh responses for a prompt right now | [Collection API](/api-reference/create-collection-request) | | Get recommended fixes and apply optimizations | [Site Optimization API](/api-reference/site-optimization/overview) | | Read retrievability and citability scores for my site and pages | [Audit Scores API](/api-reference/audit-scores/overview) | | Check whether AI crawlers can reach my site | [Crawl Readiness API](/api-reference/crawl-readiness/overview) | | Republish Agent Pages now, after a change on my site | [Force Refresh](/api-reference/agent-pages/force-refresh-overview) | | Stop serving an Agent Page now, and keep it off | [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview) | | Add an Agent Page now, including one my sitemap doesn't list | [Agent Pages Publish](/api-reference/agent-pages/publish-overview) | | Take curated (Adaptive) pages offline and keep them down | [AXP Unpublish](/api-reference/axp/unpublish) | | Create brands and manage competitors, personas, and prompts | [Configuration API](/api-reference/configuration/overview) | | Find the site ID for a domain | [List Sites](/api-reference/agent-pages/list-sites) | | Check an API key's plan and trial status | [Account API](/api-reference/account/overview) | ## All APIs These follow the sections in the sidebar. ### Measure How AI platforms talk about your brand, how AI agents and AI-referred visitors reach your site, and how often people ask AI assistants about a keyword. > [card] [Query API](/api-reference/query/overview) > > Aggregated presence, position, sentiment, and citation metrics for BI tools and reports. > [card] [Responses API](/api-reference/responses/overview) > > Every AI response Scrunch collects, with full text, citations, and evaluations. > [card] [Signals API](/api-reference/signals/overview) > > Statistically tested changes and trends in your visibility metrics. > [card] [Agent Traffic API](/api-reference/agent-traffic/overview) > > AI bot activity on your sites, plus ingestion from any CDN. > [card] [AI Referrals API](/api-reference/ai-referrals/overview) > > Push daily AI referral traffic from Adobe Analytics or other tools. > [card] [Keyword Volume API](/api-reference/keyword-volume/overview) > > Weekly AI prompt volume, Demand Score and Commercial Intent for up to 200 keywords. > [card] [Collection API](/api-reference/create-collection-request) > > Collect fresh responses for an existing prompt on demand. ### Optimize Diagnose and improve your own pages for AI. > [card] [Site Optimization API](/api-reference/site-optimization/overview) > > Recommended fixes by type or page, and the optimizations behind them. > [card] [Audit Scores API](/api-reference/audit-scores/overview) > > Retrievability and citability scores for your site and each page. > [card] [Crawl Readiness API](/api-reference/crawl-readiness/overview) > > Whether AI crawlers can reach a domain, and what blocks them. ### Deliver Serve content to AI agents through Agent Pages, and manage the curated (Adaptive) pages you deploy yourself. > [card] [Force Refresh](/api-reference/agent-pages/force-refresh-overview) > > Republish pages from your live site now, without waiting. > [card] [Agent Pages Unpublish](/api-reference/agent-pages/unpublish-overview) > > Stop serving Agent Pages now and keep them off. > [card] [Agent Pages Publish](/api-reference/agent-pages/publish-overview) > > Add pages to Agent Pages now, sitemap or not. > [card] [Curated Pages Unpublish](/api-reference/axp/unpublish) > > Take curated (Adaptive) pages offline and keep them down. ### Configure Set up your account and what Scrunch tracks. > [card] [Configuration API](/api-reference/configuration/overview) > > Create and update brands, competitors, personas, and prompts, and list sites. > [card] [Account API](/api-reference/account/overview) > > The plan, trial status, and billing period behind an API key. > [card] [Webhooks](/api-reference/webhooks/overview) > > Optimize & Deploy callbacks. Not generally available. ### Deprecated These still work for existing integrations. Don't build anything new on them. > [card] [Site Audit API](/api-reference/site-audit/overview) > > Audits individual URLs for AI search readiness. > [card] [Sitemap API](/api-reference/sitemap/overview) > > Lists and exports discovered pages with per-page AI metrics. > [card] [AXP Render API](/api-reference/axp/overview) > > Queues render jobs for pages on an AXP site. > [card] [Optimize & Deploy API](/api-reference/orchestration/overview) > > One pipeline that audits, optimizes, and deploys pages. ## Beyond the reference > [card] [Quickstart](/getting-started/quickstart-query) > > Make your first call and pull core visibility metrics. > [card] [Guides](/guides/data-mart-loading) > > Walkthroughs for data marts, agent traffic, and more. > [card] [MCP and Agent Skills](/mcp/overview) > > Use Scrunch from Claude, ChatGPT, and other AI tools. # Cancel Keyword List Source: https://developers.scrunch.com/api-reference/keyword-volume/cancel-keyword-list /api-reference/openapi.json post /{brand_id}/keyword-volume/lists/{list_id}/cancel Stop a running keyword list. Keywords not yet estimated are marked `canceled` and their weekly lookups are given back; finished keywords keep their results. Canceling a list that has already ended changes nothing. # Get Keyword List Source: https://developers.scrunch.com/api-reference/keyword-volume/get-keyword-list /api-reference/openapi.json get /{brand_id}/keyword-volume/lists/{list_id} A keyword list's status and every keyword on it, with each finished keyword's weekly volume, Demand Score and Commercial Intent score. Poll it while the list is `queued` or `running`; every 30 seconds is plenty. Results stay readable after the list ends. # Keyword Volume API: Estimate a keyword list Source: https://developers.scrunch.com/api-reference/keyword-volume/overview Estimate weekly US AI prompt volume, Demand Score and Commercial Intent for up to 200 keywords at once: start a list, then read its results as they finish. ## Overview Estimate a whole keyword list for a brand: each keyword's **weekly US AI prompt volume**, its **Demand Score** and its **Commercial Intent** score, the same numbers the **Keyword Volume** page in Scrunch shows. A list runs in the background. You start it, then poll it until it's done; each keyword's numbers appear as soon as it finishes. > [!WARNING] > > Keyword Volume has to be on for your brand. Talk to your Scrunch team to turn it on. Until it's on, every endpoint returns `404`. *** ## How it works 1. **Start a list** of up to 200 keywords. You get its `id` back at once. 2. **Get the list** about every 30 seconds until its `status` is `finished`, `failed` or `canceled`. Each keyword's numbers appear as soon as it's done, and stay readable after the list ends. 3. **Cancel it** if you started the wrong list. Keywords not yet estimated give their lookups back. All endpoints live under `https://api.scrunchai.com/v1`. | Method | Path | What it does | | - | - | - | | `POST` | `/{brand_id}/keyword-volume/lists` | Start a list. | | `GET` | `/{brand_id}/keyword-volume/lists/{list_id}` | A list's status and every keyword on it, with results. | | `POST` | `/{brand_id}/keyword-volume/lists/{list_id}/cancel` | Stop a running list. | A brand runs one list at a time. A list of new keywords takes a few minutes; keywords estimated recently come back almost at once. *** ## Authentication Send an API key as a Bearer token. Create one in Scrunch under **API Keys**. Every endpoint needs the `query` scope. ```bash theme={null} export SCRUNCH_API_TOKEN="your-key" ``` *** ## Start a list ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/1234/keyword-volume/lists" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"keywords": ["crm for small business", "email marketing tools", "project management software"]}' ``` * Up to **200 keywords**, each up to **200 characters**. * Repeats (ignoring case and spacing) are counted once, and blank entries are dropped. The response (`202`) is the list, with its `id` and how many keywords are in each status: ```json theme={null} { "id": 4182, "status": "queued", "country": "US", "item_count": 3, "counts": { "pending": 3, "running": 0, "done": 0, "failed": 0, "skipped_weekly_limit": 0, "canceled": 0 }, "created_at": "2026-11-09T21:58:20Z", "started_at": null, "finished_at": null } ``` *** ## Get the list ```bash theme={null} curl "https://api.scrunchai.com/v1/1234/keyword-volume/lists/4182" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` ```json theme={null} { "id": 4182, "status": "finished", "country": "US", "item_count": 3, "counts": { "pending": 0, "running": 0, "done": 3, "failed": 0, "skipped_weekly_limit": 0, "canceled": 0 }, "created_at": "2026-11-09T21:58:20Z", "started_at": "2026-11-09T21:58:20Z", "finished_at": "2026-11-09T22:00:36Z", "items": [ { "position": 0, "keyword": "crm for small business", "status": "done", "result": { "weekly_estimate": 9719.0, "estimated": false, "demand_score": 50, "demand_label": "Medium", "commercial_intent_score": 97, "degraded": false } }, { "position": 1, "keyword": "email marketing tools", "status": "done", "result": { "weekly_estimate": 9735.0, "estimated": false, "demand_score": 50, "demand_label": "Medium", "commercial_intent_score": 91, "degraded": false } }, { "position": 2, "keyword": "project management software", "status": "done", "result": { "weekly_estimate": 8241.0, "estimated": false, "demand_score": 47, "demand_label": "Medium", "commercial_intent_score": 87, "degraded": false } } ] } ``` The list's `status` is `queued` (waiting to start), `running`, `finished`, `failed` (stopped early) or `canceled`. Each keyword's `status` is one of: | Status | Meaning | | - | - | | `pending` | Waiting to run. | | `running` | Being estimated now. | | `done` | Finished. `result` holds its numbers. | | `failed` | Couldn't be estimated. Its weekly lookup was given back. | | `skipped_weekly_limit` | Not run: the brand's weekly lookups ran out. | | `canceled` | Not run: the list was canceled or stopped first. | ### Result fields | Field | Type | Description | | - | - | - | | `weekly_estimate` | number or null | Estimated weekly US AI prompt volume for the keyword. | | `estimated` | boolean | `true` when there was too little direct evidence for a reading, so `weekly_estimate` is modeled. | | `demand_score` | integer or null | Weekly volume on a 1 to 100 log scale: 50 is about 10,000 prompts a week. `0` when there is no demand. | | `demand_label` | string or null | The Demand Score's band: `No demand`, `Very Low`, `Low`, `Medium`, `High` or `Very High`. | | `commercial_intent_score` | integer or null | How buying-oriented the prompts for the keyword are, from 0 to 100. Higher means more commercial than AI prompts in general. Null when there wasn't enough to score. | | `degraded` | boolean | `true` when part of the estimate couldn't run, so the numbers may read low. Estimate the keyword again later. | `weekly_estimate`, `demand_score` and `demand_label` are null together when a keyword couldn't be measured. *** ## Cancel a list ```bash theme={null} curl -X POST "https://api.scrunchai.com/v1/1234/keyword-volume/lists/4182/cancel" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` Keywords not yet estimated become `canceled` and their weekly lookups are given back. Finished keywords keep their results. Canceling a list that has already ended changes nothing. *** ## Weekly lookups Keyword Volume has a weekly allowance of **lookups** per brand, shared with lookups made in Scrunch itself. * **Each keyword that hasn't been estimated recently uses one lookup.** Keywords estimated recently run without using one. * **A list bigger than what's left isn't refused.** The keywords past the limit are marked `skipped_weekly_limit`, in list order, and the rest run. * **Lookups come back** for a keyword that fails, is canceled, or turns out to have been estimated recently after all. *** ## Status codes | Status | Meaning | | - | - | | `200` | The list, with its keywords. | | `202` | The list was started or canceled. | | `401` | The API key is missing, unknown or disabled. | | `403` | The key lacks the `query` scope, or can't access the brand. | | `404` | The brand or list doesn't exist, or Keyword Volume isn't on for the brand. | | `409` | The brand already has a list running. `detail.job_id` in the body is that list: poll it or cancel it. | | `422` | The request isn't valid: no keywords, more than 200, or a keyword longer than 200 characters. | | `429` | No keyword on the list fits this week's lookups. Nothing was started or charged. | | `503` | The list couldn't be started. Nothing was charged; try again. | *** ## Tips * **Poll every 30 seconds or so.** Results land keyword by keyword; there's no need to poll faster. * **Lost the `id`?** While the list runs, starting another returns `409` with the running list's id at `detail.job_id`. * **Want a spreadsheet?** Each keyword's numbers are in `items[].result`; write them out as CSV on your side. * **Use the MCP server instead** if you're working in an AI assistant: [`start_keyword_list`](/mcp/tools#start-keyword-list), [`get_keyword_list`](/mcp/tools#get-keyword-list) and [`cancel_keyword_list`](/mcp/tools#cancel-keyword-list) do the same thing. # Start Keyword List Source: https://developers.scrunch.com/api-reference/keyword-volume/start-keyword-list /api-reference/openapi.json post /{brand_id}/keyword-volume/lists Start estimating a list of up to 200 keywords. The list runs in the background: poll Get Keyword List for each keyword's weekly volume, Demand Score and Commercial Intent score as they finish. Repeated keywords are counted once. Each keyword that hasn't been estimated recently uses one of the brand's weekly lookups. When the list needs more than the brand has left, the keywords past the limit are skipped (status `skipped_weekly_limit`) rather than the list being refused; recently estimated keywords always run, and use no lookup. A keyword that fails gives its lookup back. A brand runs one list at a time. # List Brands Source: https://developers.scrunch.com/api-reference/list-brands /api-reference/openapi.json get /brands List available brands # List Competitors Source: https://developers.scrunch.com/api-reference/list-competitors /api-reference/openapi.json get /brands/{brand_id}/competitors List competitors for a brand # List Page Audits Source: https://developers.scrunch.com/api-reference/list-page-audits /api-reference/openapi.json get /{brand_id}/page-audits List page audits in reverse chronological order > [!WARNING] > > The Site Audit API is deprecated. Existing integrations keep working, but don't build new ones on it. # List Personas Source: https://developers.scrunch.com/api-reference/list-personas /api-reference/openapi.json get /brands/{brand_id}/personas List personas for a brand # List Prompts Source: https://developers.scrunch.com/api-reference/list-prompts /api-reference/openapi.json get /{brand_id}/prompts Returns a paginated list of prompts for the specified brand, including their variants, tags, and topics. Defaults to active prompts; pass `status=paused` for paused prompts, `status=archived` for archived prompts, or `status=all` to include active, paused, and archived prompts. # List Responses Source: https://developers.scrunch.com/api-reference/list-responses /api-reference/openapi.json get /{brand_id}/responses Returns AI responses (observations) with full evaluation data, citations, and competitor analysis. Each response represents a single AI-generated answer to a tracked prompt. This endpoint provides the raw response data needed for deep analysis, audits, and research. For aggregated metrics, use the Query API instead. **Response data includes:** - Full response text from the AI platform - Brand evaluation (presence, sentiment, position) - Competitor evaluations with individual metrics - Citations with source classification (brand/competitor/other) - Prompt and persona context # Create Optimize And Deploy Pipeline Source: https://developers.scrunch.com/api-reference/orchestration/create-optimize-and-deploy-pipeline /api-reference/openapi.json post /orchestration/optimize-and-deploy/{brand_id} Create an orchestrated pipeline: audit pages, optimize content, and deploy to AXP > [!WARNING] > > The Optimize & Deploy API is deprecated. Existing integrations keep working, but don't build new ones on it. # Get Pipeline Status Source: https://developers.scrunch.com/api-reference/orchestration/get-pipeline-status /api-reference/openapi.json get /orchestration/optimize-and-deploy/{brand_id}/{token} Get the status of an optimize-and-deploy pipeline by token > [!WARNING] > > The Optimize & Deploy API is deprecated. Existing integrations keep working, but don't build new ones on it. # Optimize and Deploy Pipeline API Overview Source: https://developers.scrunch.com/api-reference/orchestration/overview Run a single async pipeline to audit pages, optimize content for AI search visibility, and deploy results to AXP with polling or webhooks. > [!WARNING] > > The Optimize & Deploy API is deprecated. Existing integrations keep working, but don't build new ones on it. ## One endpoint to rule them all The Optimize and Deploy API lets you run a multi-stage pipeline that audits your pages, optimizes their content for AI search visibility, and optionally deploys the results to AXP — all from a single API call. One endpoint to bind your audit, optimization, and deployment workflows together. Each pipeline is asynchronous. You submit URLs, receive tracking tokens, and then poll for status or receive webhook callbacks as each stage completes. > [!WARNING] > > The Optimize and Deploy API is currently in **early access** and available on request. Contact your Customer Success representative to get access enabled for your organization. *** ## How it works The pipeline chains three Scrunch products together. Each stage is optional — use only what you need. ```mermaid theme={null} flowchart LR A["Submit URLs"] --> B["🔍 Site Audit"] B --> C{"optimize?"} C -- "true" --> D["✨ Content Optimizer"] C -- "false" --> G["✅ Done"] D --> E{"deploy_axp?"} E -- "true" --> F["🚀 AXP Deploy"] E -- "false" --> G F --> G ``` | Product | Pipeline stage | What it does | Required? | | - | - | - | - | | **Site Audit** | `audit` | Evaluates AI discoverability: robots.txt, bot access, content quality, content delivery | Always runs | | **Content Optimizer** | `optimizing` | Rewrites page content to improve AI visibility for target prompts and personas | Set `optimize: true` | | **AXP (stage)** | `optimizing` | Stages optimized content to AXP for review without publishing live | Set `stage_axp: true` + `site_id` | | **AXP (deploy)** | `deploying` | Publishes optimized content to your AXP site as a new version | Set `deploy_axp: true` + `site_id` | ### Configuration per product Each product in the pipeline has its own configuration: * **Site Audit** — runs automatically on each URL, no extra config needed * **Content Optimizer** — optionally configure `target_prompts`, `target_personas`, `target_sources`, `override_suggestions`, and per-URL `custom_instructions` * **AXP** — requires a `site_id` (the RegisteredSite ULID). All URLs must belong to the site's domain. Per-URL `retain_schema_types` controls which JSON-LD schema types are kept (omit to retain all) *** ## Pipeline stages Every URL you submit moves through these stages in order: | Stage | `orchestration_status` | What happens | | - | - | - | | **Audit** | `audit` | Page is fetched and evaluated for AI discoverability (robots.txt, content quality, bot access) | | **Optimize** | `optimizing` | Content is analyzed and rewritten to improve AI visibility for your target prompts and personas | | **Deploy** | `deploying` | Optimized content is published to AXP as a new version | | **Done** | `completed` | All stages finished successfully | | **Error** | `failed` | Pipeline stopped at the failing stage | ```mermaid theme={null} stateDiagram-v2 [*] --> audit audit --> optimizing : optimize = true audit --> completed : optimize = false audit --> failed : error optimizing --> deploying : deploy_axp = true optimizing --> completed : deploy_axp = false optimizing --> failed : error deploying --> completed : success deploying --> failed : error ``` > [!NOTE] > > The optimize and deploy stages only run if you set `optimize: true` and `deploy_axp: true` in the request. With defaults, only the audit stage runs. To stage content for review without publishing live, set `stage_axp: true` instead of `deploy_axp` — see the [orchestration lifecycle guide](/guides/orchestration-lifecycle) for the stage-only flow. *** ## When to use it * You want to audit, optimize, and deploy pages without multiple API calls * You need batch processing across many URLs * You want webhook notifications when stages complete * You're building automated content optimization pipelines ## When not to use it * You only need audit results — use the **Site Audit API** directly * You want to query existing visibility data — use the **Query API** * You need manual control over each optimization — use the Scrunch dashboard *** ## Request patterns ### Simple: list of URLs Pass `urls` when every URL should use the same optimization configuration: ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "urls": [ "https://example.com/page-a", "https://example.com/page-b" ], "optimize": true, "deploy_axp": true, "site_id": "01JEXAMPLE00000000000000" }' ``` ### Detailed: per-URL overrides Pass `requests` when individual URLs need different prompts, personas, or sources: ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "requests": [ { "url": "https://example.com/page-a", "target_prompts": ["best budget airlines"], "target_personas": [{"name": "Budget Traveler"}] }, { "url": "https://example.com/page-b", "target_prompts": ["luxury travel options"] } ], "optimize": true, "deploy_axp": true, "site_id": "01JEXAMPLE00000000000000" }' ``` > [!WARNING] > > Provide either `urls` or `requests`, not both. The API will reject requests that include both fields. *** ## Tracking progress Each URL gets its own tracking token. Use it to poll for status: ```bash theme={null} curl "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234/01JABCTOKEN00000000000" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` The response includes the current `orchestration_status`, timestamps, and result data as it becomes available. For real-time updates without polling, configure webhooks to receive callbacks at each stage transition. > [card] [Set up webhooks](/api-reference/webhooks/overview) > > Get notified when audits, optimizations, and deployments complete. *** ## Error codes When a pipeline fails, the response includes a structured error code. Use these to identify what went wrong and where: | Prefix | Stage | Example codes | | - | - | - | | `ORCH-INIT` | Initialization | Invalid URL, missing site_id, domain mismatch, quota exceeded | | `ORCH-AUDIT` | Audit | Fetch failed, timeout, page not found | | `ORCH-OPT` | Optimization | No content to optimize, LLM failure, source fetch failed | | `ORCH-DEPLOY` | Deployment | Site not found, AXP publish failed | | `ORCH-HOOK` | Webhook delivery | Delivery failed, SSRF blocked, timeout | Each error includes a human-readable message and a short `error_hash` you can reference when contacting support. *** ## Relationship to other Scrunch products The Optimize and Deploy API is a composition layer that chains together three standalone Scrunch products: ```mermaid theme={null} flowchart TB subgraph "Optimize and Deploy API" direction LR SA["Site Audit API
Audit pages for
AI discoverability
"] CO["Content Optimizer
Rewrite content for
AI visibility
"] AXP["AXP
Deploy optimized
content at the edge
"] SA --> CO --> AXP end API["POST /orchestration/optimize-and-deploy"] --> SA AXP --> DONE["Results + Webhooks"] ``` * **Site Audit** is always the first stage. It runs the same checks as `POST /{brand_id}/page-audits`. * **Content Optimizer** uses audit results plus your target prompts and personas to generate optimized content. * **AXP** deploys the optimized content as a new version to your registered site. Each product can also be used independently outside of this pipeline. ### Dashboard visibility Everything the pipeline does is fully visible in the Scrunch dashboard — audit results, optimization runs, and AXP deployments all appear in their respective pages exactly as if they had been performed manually. AXP deployments are tracked in the **Version History** with full change tracking, and you can compare original vs. optimized content side by side. > [card] [Run your first pipeline](/getting-started/quickstart-orchestration) > > Go to the Optimize and Deploy Quickstart # Query Source: https://developers.scrunch.com/api-reference/query /api-reference/openapi.json get /{brand_id}/query Query the data API to retrieve aggregated observation data across multiple dimensions and metrics. This endpoint dynamically generates SQL queries based on the requested fields, allowing flexible aggregation for analytics and reporting workflows. The query endpoint returns pre-aggregated metrics grouped by the specified dimensions. Results are optimized for BI tools, reporting pipelines, and dashboards. # Query API: Aggregated AI Visibility Metrics Source: https://developers.scrunch.com/api-reference/query/overview Pull aggregated brand presence, position, sentiment, citation, and competitor metrics across AI platforms and date ranges from Scrunch. ## Overview The Query API provides aggregated access to Scrunch’s core AI visibility metrics. It is the same data that powers the Scrunch dashboard, exposed in a flexible, queryable format for analytics and reporting workflows. This API is optimized for **scale and performance**, making it ideal for BI tools, reporting pipelines, scheduled exports, and automation where response-level detail is not required. Each request returns pre-aggregated metrics based on the dimensions you select. *** ## What the Query API includes The Query API returns aggregated metrics such as: * Brand presence percentage * Brand position score * Brand sentiment score * Competitor presence percentage * Sub-brand presence, position, and sentiment * Citation rate, share of voice, and citation volume * Response counts These metrics can be grouped by dimensions including: * Date (day, week, month, quarter, year) * Prompt or prompt metadata * Persona * Tag * Platform * Competitor * Sub-brand * Source URL * Branded vs non-branded All results are **derived summaries**, not raw AI responses. Metrics cover history from **active** and **paused** prompts; **archived** prompts are excluded. Persona state does not affect which prompts' history is counted, so aggregates stay consistent with your configured prompt list. *** ## When to use the Query API Use the Query API when you need: * Weekly or monthly reporting * Trend analysis over time * Brand and competitor visibility metrics * Aggregation by date, persona, tag, platform, or prompt * Data for dashboards (Looker, Power BI, Tableau) * Large batch metric pulls for automation or reporting The Query API is designed to answer questions like: “How is our AI visibility changing over time?”\ “How do we compare to competitors by topic or platform?” *** ## When not to use the Query API The Query API is not appropriate if you need: * Raw AI response text * Citation URLs or snippets * Per-response competitor sentiment or position * Full message-level audits or research For those use cases, use the **Responses API**, which exposes the underlying response records in full detail. *** ## Example query ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/query?fields=date_week,brand_presence_percentage,brand_sentiment_score" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` You can narrow results with `filters` (pre-aggregation, on dimensions) and `having` (post-aggregation, on metrics): ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/query?fields=date_week,ai_platform,brand_presence_percentage&filters=ai_platform:ChatGPT|Claude&having=brand_presence_percentage:gt:0.1" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` Break responses out by the individual fan-out queries an AI engine ran, instead of by the prompt you submitted: ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/query?fields=query_fanouts,responses" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` Break the brand / competitor / other ownership split out across responses — the shape BI tools (Looker, Power BI, Tableau) typically chart: ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/query?fields=owner,responses" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` *** ## Two ways to query The Query API exposes two endpoints that share the same dimensions and metrics: * **`GET /v1/{brand_id}/query`** — URL-parameter form. Use it for simple pulls and BI integrations that prefer query strings. * **`POST /v2/query/{brand_id}`** — JSON-body form. Use it when you need post-aggregation thresholds (`HAVING`), negated filters, or period-over-period comparison in a single request. See the [Structured Query Endpoint](/api-reference/query/structured-query) reference. Both endpoints require an API key with access to the target brand; the `POST /v2` endpoint additionally requires the **Query** scope on the key. *** ## Fields reference Specify fields in the `fields=` array to control what is returned. **Dimensions** determine how metrics are grouped — querying a dimension alone returns its unique values. **Metrics** are numeric measures — querying a metric alone returns its overall aggregate across all data. ### Dimensions | Field | Type | Description | Constraints | Prompt relationship | | - | - | - | - | - | | `prompt_id` | Number | Unique identifier for the prompt | — | — | | `prompt` | String | Full text of the prompt submitted to the AI platform | — | — | | `date_month` | String | Month responses were collected, truncated to the first day of the month. Use for monthly trend reporting. | Last 90 days only | Many to many | | `date_week` | String | Calendar week responses were collected, truncated to the start of the week. Use for weekly trend reporting. | Last 90 days only. Recommend keeping date filters week-aligned. | Many to many | | `date` | String | Specific date responses were collected. Use for daily granularity. | Last 90 days only | Many to many | | `source_url` | String | Cited page found in AI responses, keyed by page identity: lowercased host + path (for example, `example.com/pricing`). Scheme, `www.`, port, query string, fragment, and trailing slash are dropped, so every spelling a model emits for one page (`https://www.example.com/Pricing`, `example.com/pricing?utm_source=x`) rolls into a single row. Use to rank the individual pages cited in AI answers. | All query parameters are dropped — URLs that differ only by query string (for example, `youtube.com/watch?v=…`) group into one row per path. | Many to many | | `domain` | String | Registered domain of a citation source (e.g. `example.com`). Use to roll `source_url` data up to the domain level. | — | Many to many | | `owner` | String (Enum) | Ownership classification of a citation's domain. Values: `brand` (the tracked brand), `competitor` (a configured competitor), `other` (everything else). Use to chart the brand vs. competitor vs. third-party split, or filter to a single ownership class. | Filterable (closed vocabulary — `brand`, `competitor`, `other`). See [Filtering by citation source owner](#filtering-by-citation-source-owner). | Many to many | | `source_type` | String (Enum) | Ownership classification of a citation source. Values: `brand`, `competitor`, `other` (third-party in the Scrunch UI). Equivalent to `owner` and retained for backward compatibility — new integrations should prefer `owner`. | — | Many to many | | `source_domain` | String | Host of a citation source, lowercased and `www`-stripped (for example, `nytimes.com`). Use to group citations by publisher rather than by individual URL. | Computed on the raw query path — cannot be combined with citation metrics (use `domain` for that) and is not filterable. | Many to many | | `source_topic` | String | Topic tags assigned to a cited source's domain in your Scrunch brand configuration. Use to break citation metrics down by the subject areas of the pages that cite you (for example, "Product reviews" vs. "How-to guides"). Sources with no configured topics fall into an explicit `Untagged` bucket rather than being dropped. | Source-grain breakdown — only valid alongside citation metrics. Not filterable. List-valued: a source with multiple topics contributes one row per topic, so additive citation metrics (`citation_count`, `citation_unique_domains`) can double-count across a source's topics; rate metrics (`citation_rate`, mention rates) are unaffected. | Many to many | | `citation_segment` | String | Name of the citation segment a cited source falls into, from your Scrunch brand configuration, plus an explicit `Unsegmented` bucket for sources that match no segment. Each source is labeled by its first matching segment, so overlapping segments still produce a clean partition. A segment matches by its configured mode: **prefix** (the default — an entry also captures its subpaths) or **exact** (an entry captures only that page; letter case, `www.`, ports, query strings, and trailing slashes are ignored, subpaths are not matched). Exact entries use the same page identity as the `source_url` dimension, so a page selected by an exact segment appears as a single breakdown row. Managed **Agent Pages** segments (named `Agent Pages — `) are created automatically for each site serving AXP-optimized pages, always match exactly, and mirror the deployed page set with no manual upkeep. | Source-grain breakdown — only valid alongside citation metrics. Managed Agent Pages segments apply the *current* page set to the whole date range: citations from before a page was deployed are counted, and a retired page drops out of history. | Many to many | | `persona_id` | Number | Unique identifier for the persona associated with the prompt | — | One to many | | `persona_name` | String | Name of the persona associated with the prompt. Personas represent audience segments or geographic configurations. | — | One to many | | `competitor_id` | Number | Unique identifier for a competitor tracked in your Scrunch brand configuration | — | Many to many | | `competitor_name` | String | Name of the competitor. Use alongside competitor metrics to analyze individual competitor visibility. | — | Many to many | | `sub_brand_id` | Number | Unique identifier for a sub-brand tracked in your Scrunch brand configuration. Use alongside sub-brand metrics to analyze a specific product line, region, or division. | — | Many to many | | `ai_platform` | String (Enum) | AI platform that generated the response. Values: `chatgpt`, `perplexity`, `google_ai_overviews`, `meta`, `claude` | — | Many to many | | `tag` | String | User-defined tag attached to prompts in the Scrunch UI. Use to group and filter by custom categories. | — | Many to many | | `branded` | Boolean | Whether the prompt includes the brand name or an alternate brand name. Use to compare branded vs. unbranded query performance. | — | One to many | | `stage` | String | Stage of the customer journey the prompt is mapped to. Values are resolved from your brand's configured stages, so they vary per brand. Default sets: intent — `Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other`; funnel — `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other`. Brands that rename or add stages return those custom names. Filter values pass through verbatim — a value that doesn't match any of the brand's stages matches zero rows rather than erroring. | — | One to many | | `prompt_topic` | String | Key topic extracted from or assigned to the prompt. Use to group performance by topic area. | — | Many to many | | `country` | String | 2-letter ISO country code for which the response was retrieved, based on the persona or brand default configuration. | — | One to many | | `language` | String | 2-letter ISO 639-1 code of the language the prompt variant is written in (for example, `en` or `de`). This is the language declared on the prompt, not a language detected from the response. Use to compare performance across languages when you track the same prompt in multiple languages. | — | One to many | | `position_bucket` | String (Enum) | Where your brand appears inside a response when it is mentioned. Values: `top`, `middle`, `bottom`. Use to break mentions out by prominence — for example, to see what share of mentions land in the top of the answer. | Conditional dimension: rows where the brand is not mentioned are excluded from the breakdown. See [Breaking mentions down by a conditional dimension](#breaking-mentions-down-by-a-conditional-dimension). | Many to many | | `sentiment_band` | String (Enum) | How your brand is talked about inside a response when it is mentioned. Values: `positive`, `mixed`, `negative`, `none`. Use to break mentions out by tone — for example, to see what share of mentions are positive on each platform. | Conditional dimension: rows where the brand is not mentioned are excluded from the breakdown. See [Breaking mentions down by a conditional dimension](#breaking-mentions-down-by-a-conditional-dimension). | Many to many | | `rank` | Number | First-occurrence rank of the entity inside a response, where `1` is the first mention. Use to chart the rank distribution — for example, to see what share of mentions land at `#1` vs `#2` vs `#3`. | Conditional dimension: rows where the entity is not ranked (not mentioned) are excluded from the breakdown. See [Breaking mentions down by a conditional dimension](#breaking-mentions-down-by-a-conditional-dimension). | Many to many | | `query_fanouts` | String | Individual search query an AI engine generated internally during query fan-out. Each row in the response represents one fan-out query; observations without a fan-out yield zero rows for this dimension. Use to break metrics down by the underlying searches an AI platform actually ran. | Not filterable. Forces the raw query path, which can be slower than other dimensions. | Many to many | ### Metrics | Field | Type | Description | Aggregation | Constraints | | - | - | - | - | - | | `responses` | Number | Total number of AI responses collected for the selected dimensions. The base volume metric. | Count | — | | `unique_prompts` | Number | Distinct count of prompt variants that produced responses in the selected window. A prompt expands into one variant per platform × persona × geography × language × scenario combination, and variants are what Scrunch actually monitors — so this is what the Scrunch dashboard's "Prompts" tile reports. Use to size the underlying variant set behind any aggregate. | Distinct count | — | | `brand_presence_percentage` | Number | Percentage of responses in which your brand was mentioned. The primary measure of AI visibility. | Average | — | | `brand_unique_prompts` | Number | Distinct count of prompt variants where your brand was mentioned in at least one response. Variant-grain, matching `unique_prompts`. | Distinct count | — | | `brand_unique_responses` | Number | Distinct count of responses that mentioned your brand. | Distinct count | — | | `brand_share_of_voice` | Number | Your brand's share of mentions across the full competitive set. Computed as your brand's mention responses divided by the total mention responses for your brand plus all active competitors. Across a given slice, `brand_share_of_voice` plus the sum of `competitor_share_of_voice` for every competitor equals 1. Use to compare visibility on a normalized scale that ignores prompts where nobody was mentioned. | Ratio | Range: 0–1. The denominator always reflects the full brand-plus-competitors set, even if you filter to specific competitors. See [Share of Voice supported breakdowns and filters](#share-of-voice-supported-breakdowns-and-filters). | | `brand_position_score` | Number | Weighted score (0–100) reflecting how prominently your brand appears across all responses. Derived from the distribution of Top, Middle, and Bottom positions — higher scores indicate more top-of-response appearances. **Note:** the Scrunch dashboard displays the raw share of Top-position responses; this score is a continuous aggregate and will differ from that figure. | Average | Range: 0–100 | | `brand_sentiment_score` | Number | Weighted score (0–100) reflecting overall sentiment toward your brand across all responses. Derived from the distribution of Positive, Mixed, Negative, and None sentiments — higher scores indicate a more positive distribution. **Note:** the Scrunch dashboard displays the raw share of Positive-sentiment responses; this score is a continuous aggregate and will differ from that figure. | Average | Range: 0–100 | | `brand_avg_rank` | Number | Average first-occurrence rank of your brand among same-type entities mentioned in a response, where `1` is the first mention. **Lower is better.** Only responses in which your brand was ranked contribute to the average — responses where your brand was not mentioned are skipped, so this metric measures positioning among ranked appearances only. Pair with `brand_presence_percentage` to see how often your brand shows up at all. | Average | Starts at 1. Computed over ranked appearances only. | | `competitor_presence_percentage` | Number | Percentage of responses in which the competitor was mentioned. | Average | Must be used with `competitor_id` or `competitor_name` (or both) | | `competitor_position_score` | Number | Weighted score (0–100) reflecting how prominently the competitor appears across all responses. Derived from the distribution of Top, Middle, and Bottom positions — see note on `brand_position_score` regarding differences from dashboard figures. | Average | Range: 0–100. Must be used with `competitor_id` or `competitor_name` (or both) | | `competitor_sentiment_score` | Number | Weighted score (0–100) reflecting overall sentiment toward the competitor across all responses. Derived from the distribution of Positive, Mixed, Negative, and None sentiments — see note on `brand_sentiment_score` regarding differences from dashboard figures. | Average | Range: 0–100. Must be used with `competitor_id` or `competitor_name` (or both) | | `competitor_avg_rank` | Number | Average first-occurrence rank of the competitor among same-type entities mentioned in a response, where `1` is the first mention. **Lower is better.** Only responses in which the competitor was ranked contribute to the average; responses where the competitor was not mentioned are skipped. Pair with `competitor_presence_percentage` to see how often the competitor shows up at all. | Average | Starts at 1. Computed over ranked appearances only. Must be used with `competitor_id` or `competitor_name` (or both) | | `competitor_unique_prompts` | Number | Distinct count of prompt variants where the competitor was mentioned in at least one response. Variant-grain, matching `unique_prompts`. | Distinct count | Must be used with `competitor_id` or `competitor_name` (or both) | | `competitor_unique_responses` | Number | Distinct count of responses that mentioned the competitor. | Distinct count | Must be used with `competitor_id` or `competitor_name` (or both) | | `competitor_share_of_voice` | Number | The competitor's share of mentions across the full competitive set. Computed as the competitor's mention responses divided by the total mention responses for your brand plus all active competitors. Pair with `competitor_id` or `competitor_name` for a per-competitor breakdown; without that dimension the value aggregates every competitor. The denominator stays fixed to the full set, so filtering competitor rows does not rescale the share. | Ratio | Range: 0–1. Must be used with `competitor_id` or `competitor_name` (or both) for per-competitor values. See [Share of Voice supported breakdowns and filters](#share-of-voice-supported-breakdowns-and-filters). | | `sub_brand_presence_percentage` | Number | Percentage of responses in which the sub-brand was mentioned. Use to measure AI visibility for a specific product line, region, or division. | Average | Pair with `sub_brand_id` to break out by sub-brand, or filter `sub_brand_id` to isolate one | | `sub_brand_position_score` | Number | Weighted score (0–100) reflecting how prominently the sub-brand appears across all responses. Derived from the distribution of Top, Middle, and Bottom positions — see note on `brand_position_score` regarding differences from dashboard figures. | Average | Range: 0–100 | | `sub_brand_sentiment_score` | Number | Weighted score (0–100) reflecting overall sentiment toward the sub-brand across all responses. Derived from the distribution of Positive, Mixed, Negative, and None sentiments — see note on `brand_sentiment_score` regarding differences from dashboard figures. | Average | Range: 0–100 | | `sub_brand_unique_prompts` | Number | Distinct count of prompt variants where the sub-brand was mentioned in at least one response. Variant-grain, matching `unique_prompts`. | Distinct count | — | | `sub_brand_unique_responses` | Number | Distinct count of responses that mentioned the sub-brand. | Distinct count | — | | `sub_brand_share_of_voice` | Number | The aggregate share of mentions across the sub-brands you track under your brand. Computed as present `(sub_brand, response)` pairs over the total present pairs across all tracked sub-brands, so the values across a sub-brand set sum to 1. Use to gauge how attention is distributed across your own product lines, regions, or other sub-brand groupings. The denominator reflects the full tracked sub-brand set and does not shrink when you filter to a subset. | Ratio | Range: 0–1. Runs on the sub-brand query path, which supports a different breakdown surface than `brand_share_of_voice` / `competitor_share_of_voice` — see [Share of Voice supported breakdowns and filters](#share-of-voice-supported-breakdowns-and-filters). `tag` and `prompt_topic` are accepted as filters but rejected as breakdown dimensions; the `prompt` breakdown is not available on this path. | | `market_presence_percentage` | Number | Share of responses that mention **any** tracked entity — your brand or any active competitor. Note: this is response-level coverage, not the sum of per-entity mention rates. Use as the pooled "All (brands & competitors)" mention rate. | Average | Range: 0–1. Cannot be combined with brand, competitor, or sub-brand mention metrics in the same request, or with breakdowns scoped to a single entity (`competitor_id`, `competitor_name`, `sub_brand_id`). | | `market_position_score` | Number | Volume-weighted position score (0–100) pooled across every tracked entity. Each entity-mention contributes once, so this reconciles with per-entity `brand_position_score` / `competitor_position_score` weighted by mention volume. | Average | Range: 0–100. Same compatibility constraints as `market_presence_percentage`. | | `market_sentiment_score` | Number | Volume-weighted sentiment score (0–100) pooled across every tracked entity. Reconciles with per-entity sentiment scores weighted by mention volume. | Average | Range: 0–100. Same compatibility constraints as `market_presence_percentage`. | | `market_avg_rank` | Number | Volume-weighted average first-occurrence rank pooled across every tracked entity. **Lower is better.** Each ranked entity-mention contributes once; unranked rows are skipped. | Average | Starts at 1. Same compatibility constraints as `market_presence_percentage`. | | `citation_rate` | Number | Share of all responses in the slice that include at least one citation, regardless of who owns it. The denominator is every response in the slice. | Average | Range: 0–1 | | `brand_citation_rate` | Number | Share of all responses in the slice that cite at least one brand-owned domain. The denominator is every response in the slice, matching `brand_presence_percentage` semantics for citations. | Average | Range: 0–1 | | `competitor_citation_rate` | Number | Share of all responses in the slice that cite at least one competitor-owned domain. | Average | Range: 0–1. Cannot be combined with `competitor_id` / `competitor_name` (HTTP 400) — scope to specific competitors with the `cited_competitor_name` filter. | | `brand_citation_share_of_voice` | Number | Of responses that cite anything, the share that cite at least one brand-owned domain. The denominator is responses with at least one citation — use this to ask "when the AI cites sources, how often is it citing us?" | Ratio | Range: 0–1 | | `competitor_citation_share_of_voice` | Number | Of responses that cite anything, the share that cite at least one competitor-owned domain. | Ratio | Range: 0–1. Cannot be combined with `competitor_id` / `competitor_name` (HTTP 400) — scope with the `cited_competitor_name` filter. | | `citation_count` | Number | Total citation occurrences across responses in the slice. A response that cites three URLs contributes three. Entity-agnostic — counts every citation regardless of owner. | Sum | — | | `brand_citation_count` | Number | Total citation occurrences that resolve to a brand-owned domain. | Sum | — | | `competitor_citation_count` | Number | Total citation occurrences that resolve to a competitor-owned domain. | Sum | Cannot be combined with `competitor_id` / `competitor_name` (HTTP 400) — scope with the `cited_competitor_name` filter. | | `citation_unique_responses` | Number | Distinct count of responses that contain at least one citation. | Distinct count | — | | `brand_citation_unique_responses` | Number | Distinct count of responses that cite at least one brand-owned domain. | Distinct count | — | | `competitor_citation_unique_responses` | Number | Distinct count of responses that cite at least one competitor-owned domain. | Distinct count | Cannot be combined with `competitor_id` / `competitor_name` (HTTP 400) — scope with the `cited_competitor_name` filter. | | `citation_unique_domains` | Number | Distinct count of citation hosts (`www`-stripped) across responses in the slice. | Distinct count | — | | `citation_unique_response_domains` | Number | Distinct count of (response, domain, owner) triples. A response citing `example.com` under four URLs contributes one; a response citing six distinct domains contributes six. Use this to reproduce the Classic Citations page's composition grain (the "share of citations by owner" donut). | Distinct count | Pair with `owner`, `domain`, or another response-grain dimension. Grouping by `source_url` puts the page back in the key and inflates the total; `citation_segment` can place one triple in two segments. | | `brand_citation_unique_domains` | Number | Distinct count of brand-owned citation hosts (`www`-stripped). | Distinct count | — | | `competitor_citation_unique_domains` | Number | Distinct count of competitor-owned citation hosts (`www`-stripped). | Distinct count | Cannot be combined with `competitor_id` / `competitor_name` (HTTP 400) — scope with the `cited_competitor_name` filter. | | `sub_brand_citation_rate` | Number | Share of responses (0–1) that cite a source owned by the sub-brand. Use to measure how often AI grounds answers in your sub-brand's own web properties. | Average | Pair with `sub_brand_id` for per-sub-brand values (recommended — without it the value aggregates across all tracked sub-brands). Requires sub-brands to be configured for the brand. | | `sub_brand_citation_share_of_voice` | Number | Of responses that cite any source, the share (0–1) that cite a sub-brand-owned source. Use to compare a sub-brand's citation footprint against all cited domains. | Ratio | Pair with `sub_brand_id` for per-sub-brand values. | | `sub_brand_citation_count` | Number | Total citation occurrences across responses where the cited domain is owned by the sub-brand. | Count | Pair with `sub_brand_id` for per-sub-brand values. | | `sub_brand_citation_unique_responses` | Number | Distinct count of responses that include at least one citation to a sub-brand-owned source. | Distinct count | Pair with `sub_brand_id` for per-sub-brand values. | | `sub_brand_citation_unique_domains` | Number | Distinct count of sub-brand-owned domains (www-stripped) cited across responses. | Distinct count | Pair with `sub_brand_id` for per-sub-brand values. | | `brand_citation_mention_rate` | Number | Share of distinct cited URLs where your brand is named **in the content of the cited page itself** — not in the AI response text. Use to prioritize third-party outreach: which publishers already talk about you when the AI cites them. Distinct from `brand_presence_percentage` (which measures the AI response) and `brand_citation_rate` (which measures whether a brand-owned domain was cited). | Ratio | Range: 0–1. Computes on the source-grain path (forced): at aggregate grain and by `domain` it is a continuous rate; by `source_url` it collapses to a Yes/No (0 or 1) per page. Cannot be combined with `competitor_id` / `competitor_name`. | | `competitor_citation_mention_rate` | Number | Share of distinct cited URLs where a competitor is named in the content of the cited page. Pair with `cited_competitor_name` (as a filter, breakdown, or both) to scope to a specific competitor or list the top mentioned competitors per source; without it, the metric covers all active competitors. | Ratio | Range: 0–1. Computes on the source-grain path (forced). To scope to specific competitors use the `cited_competitor_name` filter — combining with `competitor_id` / `competitor_name` returns HTTP 400. | | `weighted_index` | Number | **Influence Score.** Per-source ranking metric that combines how often a cited source appears with how many distinct prompts cite it. Higher scores indicate sources that both show up often and cover a broad range of prompts — the sources most worth prioritizing for outreach. Entity-agnostic (no brand/competitor variant); ranks every cited source in the slice. | Aggregate (per source) | **Requires a `domain` or `source_url` breakdown** — Influence Score only makes sense when one row equals one cited source. Coarser breakdowns (`owner`, `citation_segment`, `source_topic`) collapse many sources into a row and inflate the score, and are rejected with HTTP 400. Add `domain` or `source_url` to `fields`, or drop the metric. | | `cross_grain_presence_percentage` | Number | Cross-grain pooled presence rate — a single line that counts a response as "present" if any selected entity across both the brand grain (your brand plus selected competitors) *and* the sub-brand grain (selected sub-brands) appeared. Use to plot brand + sub-brand visibility as one combined line without double-counting a response that mentions entities on both grains. | Ratio | Range: 0–1. Presence-only — no position, sentiment, rank, or share-of-voice variant. See [Cross-grain pooled presence](#cross-grain-pooled-presence). | > [!NOTE] > > Citation metrics are computed on the staging source path. To break citations down by source, pair them with the `domain`, `source_url`, `owner`, `cited_competitor_name`, `citation_segment`, or `source_topic` dimensions — these activate the source-grain breakdown. You can also break citation metrics down by `prompt` (on its own or combined with a source-grain dimension) to see per-prompt citation rates. Mixing citation fields with high-cardinality dimensions can be slower than mention-only queries; keep date windows and field lists tight. > [!NOTE] > > **Pooled "All (brands & competitors)" metrics.** The `market_*` metrics roll mention, position, sentiment, and rank up across your brand and every active competitor in a single volume-weighted average. Use them to track the overall AI conversation about your category — not the sum of per-entity rates. They run as their own query path, so they cannot be mixed with brand, competitor, or sub-brand metrics in the same request; pull them on their own and combine the series downstream. > [!WARNING] > > Citation metrics cannot be combined with fields that force the raw query path — `competitor_id`, `competitor_name`, the competitor mention metrics, `ai_platform_search_enabled`, or `source_domain` — such requests return `HTTP 400`. To scope competitor citation metrics to specific competitors, use the `cited_competitor_name` filter; to break citations down by publisher, use `domain` instead of `source_domain`. The `prompt` dimension is supported: combining it with a citation metric (optionally alongside a source-grain dimension such as `domain` or `source_url`) returns the per-prompt citation rate. > [!NOTE] > > **Active-entity scope.** Sub-brand metrics, the `sub_brand_id` breakdown, competitor citation metrics, and the `cited_competitor_name` filter and breakdown only count rows tied to currently active sub-brands and competitors. Archived sub-brands (including those whose parent competitor is no longer active) and deactivated competitors are excluded from numerators, share-of-voice denominators, and breakdown values. Re-activate the entity in your Scrunch brand configuration to bring its history back into results. #### Share of Voice supported breakdowns and filters Mention Share of Voice (`brand_share_of_voice`, `competitor_share_of_voice`) divides an entity's present-response count by the full brand-plus-active-competitors set. Adding a breakdown re-buckets both sides of that ratio, so each row divides by its **own** slice's present-set — never a global total. Only the dimensions listed below produce a valid partition; anything else returns HTTP `400`. **Supported breakdowns.** `date`, `date_week`, `date_month`, `date_quarter`, `date_year`, `ai_platform`, `stage`, `persona_name`, `country`, `language`, `prompt`, `competitor_id`, `competitor_name`. The `prompt` breakdown partitions the denominator per prompt, so each row is that prompt's share of voice against the full competitive set on the same prompt. **Supported filters.** All of the supported breakdowns are also filterable, plus `prompt_id`, `tag`, `prompt_topic`, and `ai_platform_search_enabled`. `tag` and `prompt_topic` are filter-only for Share of Voice — as breakdowns they would fan a multi-tag response across array elements in the numerator while it counts once in the whole-set denominator, inflating the share. **Not supported.** The conditional dimensions `position_bucket`, `sentiment_band`, and `rank` are rejected as both breakdowns and filters — they describe one entity's row within a response, so they cannot narrow the whole-set denominator. Source-grain fields (`domain`, `source_url`, `owner`, `cited_competitor_name`, `citation_segment`, `source_topic`, `source_type`, `source_domain`) are citation-path only and cannot combine with mention Share of Voice. **Sub-brand Share of Voice.** `sub_brand_share_of_voice` runs on the sub-brand query path. It accepts `tag` and `prompt_topic` as filters (parity with `sub_brand_citation_share_of_voice`) but still rejects them as breakdowns. The `prompt` (text) dimension is not available on this path at all — for a per-prompt sub-brand slice, break down by `prompt_id` instead. ```bash theme={null} # Weekly mention share of voice, broken down by prompt, filtered to a tag curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,prompt,brand_share_of_voice&filters=tag:pricing" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` #### Example: citation metrics ```bash theme={null} # Weekly brand citation rate and share of voice on ChatGPT curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,brand_citation_rate,brand_citation_share_of_voice&filters=ai_platform:ChatGPT" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ```bash theme={null} # Top citation domains, ranked by occurrence curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=domain,citation_count,citation_unique_responses&having=citation_count:gte:5" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` #### Example: Influence Score for outreach prioritization Rank cited domains by Influence Score alongside the share of pages that already mention your brand — a shortlist of high-influence sources you don't yet appear on: ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=domain,weighted_index,brand_citation_mention_rate&having=weighted_index:gte:1" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` #### Example: citations broken down by domain topic Break down citation volume by the topic tags configured for each cited source's domain. Untagged sources appear in an explicit `Untagged` bucket: ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=source_topic,citation_unique_domains,citation_count" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` #### Example: pooled market metrics ```bash theme={null} # Weekly pooled mention rate and position score across your brand + all competitors curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,market_presence_percentage,market_position_score" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` #### Example: sub-brand citation rate by platform Break down how often each AI platform cites a specific sub-brand's owned domains: ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=ai_platform,sub_brand_id,sub_brand_citation_rate&filters=sub_brand_id:$SUB_BRAND_ID" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` *** ## Cross-grain pooled presence `cross_grain_presence_percentage` pools presence across the **brand grain** (your brand plus selected competitors) and the **sub-brand grain** (selected sub-brands) into one presence rate. A response counts as present if *any* selected entity on *either* grain appeared, so a response that mentions both a brand-grain entity and a sub-brand-grain entity is counted once — not twice. Use it when you want to chart brand + sub-brand visibility as a single combined series (for example, "Own brand + all sub-brands" or "Own brand + one sub-brand + one competitor") without the double-counting you'd get from summing the per-grain rates. ### Selecting which entities join the pool By default the pool includes your own brand plus every active competitor and every active sub-brand. Narrow either grain with a positive filter on that grain's identity field: * `filters=competitor_name:` — narrows the competitor branch of the brand grain. Your own brand always stays in the pool. * `filters=sub_brand_id:` — narrows the sub-brand grain to the named sub-brand(s). * `filters=ownership:competitor` — signals "include the competitor branch" when you want all active competitors in the pool but have no specific names to list. Without either this filter or a `competitor_name` list, the pool drops the competitor branch entirely and uses your own brand alone on the brand grain. Multiple positive values on the same identity field are combined as `IN (...)` — the pool is the union of the named entities, matching what an Explorer multi-select produces. Negated identity filters (`competitor_name:!`, `sub_brand_id:!`) are rejected with `HTTP 400`. ### Supported breakdowns Cross-grain pooling is presence-only, so it accepts only the non-conditional lens dimensions: `date`, `date_week`, `date_month`, `date_quarter`, `date_year`, `ai_platform`, `stage`, `persona_name`, `persona_id`, `country`, `language`, `branded`, `prompt_id`. Entity-identity breakdowns (`competitor_id`, `competitor_name`, `sub_brand_id`) and source-grain dimensions (`domain`, `source_url`, `owner`, `source_domain`) are not supported — the pooled series has no per-entity split. Position, sentiment, rank, and share-of-voice have no cross-grain analogue and are not available either. ### Example Weekly combined presence for your brand, a chosen competitor, and one sub-brand on ChatGPT: ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,cross_grain_presence_percentage&filters=competitor_name:Acme&filters=sub_brand_id:17&filters=ai_platform:ChatGPT" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` Weekly combined presence for your brand plus every active sub-brand (no competitor leg): ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,cross_grain_presence_percentage" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` > [!NOTE] > > Only active competitors and sub-brands contribute to the pool. Archived competitors and sub-brands (including those whose parent competitor is no longer active) are excluded from the numerator, so re-activate them in your brand configuration to bring their history back in. *** ## Filtering results The Query API supports two filter parameters that narrow what is returned. Both can be combined in the same request and both can be repeated to apply multiple filters (combined with AND). ### Dimension filters (`filters`) Use `filters` to narrow rows **before** aggregation runs. Each filter takes the form `field:value`. Combine multiple values with `|` for an `IN` match, and prefix the value with `!` to negate. ```bash theme={null} # Only ChatGPT and Claude, branded prompts only curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,brand_presence_percentage&filters=ai_platform:ChatGPT|Claude&filters=branded:true" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ```bash theme={null} # Exclude a specific competitor curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=competitor_name,competitor_presence_percentage&filters=competitor_id:!42" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ```bash theme={null} # Weekly sentiment for a specific sub-brand, broken out by prompt topic curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,prompt_topic,sub_brand_sentiment_score&filters=sub_brand_id:17" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` **Filterable dimensions:** `prompt_id`, `persona_id`, `persona_name`, `ai_platform`, `ai_platform_search_enabled`, `tag`, `competitor_id`, `competitor_name`, `sub_brand_id`, `branded`, `stage`, `prompt_topic`, `country`, `language`, `position_bucket`, `sentiment_band`, `rank`, `date`, `date_week`, `date_month`, `date_quarter`, `date_year`, `owner`. `rank` values must be positive integers (`1`, `2`, …); non-numeric values return `HTTP 400`. `owner` accepts a closed vocabulary — `brand`, `competitor`, `other`. Any other value returns `HTTP 400`; see [Filtering by citation source owner](#filtering-by-citation-source-owner). `source_url`, `domain`, `source_domain`, `source_topic`, `prompt`, and `query_fanouts` are not filterable. #### Filter for prompts with no tag or topic Pass the reserved token `__none__` as a filter value on `tag` or `prompt_topic` to match prompts that carry no tag or no topic. Use it to isolate the untagged tail of your prompt set. ```bash theme={null} # Only untagged prompts curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,brand_presence_percentage&filters=tag:__none__" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` Combine `__none__` with real values using `|` — the filter matches the untagged prompts **or** the named tags: ```bash theme={null} # Untagged prompts plus the "Core" tag curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=tag,brand_presence_percentage&filters=tag:__none__|Core" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` Prefix with `!` to invert the whole filter — for example, prompts that carry at least one tag: ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=brand_presence_percentage&filters=tag:!__none__" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` Only `tag` and `prompt_topic` accept `__none__`. Sending it on any other dimension returns `HTTP 400`. A tag literally named `__none__` becomes unreachable by equality — the token always resolves to the absence match. Rename such a tag if you need to filter for it directly. #### Filter and group by the same tag or topic A prompt can carry several tags and topics. When you filter on `tag` or `prompt_topic` and also include that dimension in `fields`, Scrunch returns rows only for the values you filtered on. Other tags or topics that the matching prompts also carry don't appear as rows. ```bash theme={null} # Returns rows for "Pricing" and "Support" only curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=prompt_topic,brand_presence_percentage&filters=prompt_topic:Pricing|Support" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` If you include `__none__` in the filter, the response also contains a row for prompts with no tag or topic. In that row, the dimension value is `null`. A negated filter (`!`) narrows the prompts but adds no rows. #### Filtering by citation source owner `owner` scopes results to citations owned by the brand, a configured competitor, or a third party. Values are a closed vocabulary: `brand`, `competitor`, `other`. Any other value returns `HTTP 400`. The filter behaves at two grains depending on what else is in `fields`: * **Response grain (default).** Without a source-grain breakdown, the filter keeps whole responses that cite at least one source of that owner. Every metric in the request is scoped to those responses. * **Source grain (with `domain`, `source_url`, `citation_segment`, or `source_topic` in `fields`).** The filter narrows the source-grain rows to the matching sources only, so a citation-domain breakdown returns just the domains owned by the selected class. Applying an `owner` filter creates citation context, so it must be paired with a citation metric (for example `citation_count`, `brand_citation_rate`, `citation_unique_responses`). Pairing `owner` with only response-level metrics such as `responses` returns `HTTP 400` — use the `owner` breakdown for that shape instead. ```bash theme={null} # Responses that cite at least one competitor-owned source, weekly curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,citation_unique_responses&filters=owner:competitor" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ```bash theme={null} # Top third-party citation domains curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=domain,citation_count&filters=owner:other" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ### Metric filters (`having`) Use `having` to filter on **aggregated** metric values after `GROUP BY` runs. Each entry takes the form `metric:operator:value`. | Operator | Meaning | | - | - | | `gt` | Greater than | | `gte` | Greater than or equal | | `lt` | Less than | | `lte` | Less than or equal | | `eq` | Equal | | `neq` | Not equal | ```bash theme={null} # Weeks where presence is above 10% and at least 50 responses were collected curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=date_week,brand_presence_percentage,responses&having=brand_presence_percentage:gt:0.1&having=responses:gte:50" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` The metric you reference in `having` must also appear in `fields`. *** ## Breaking mentions down by a conditional dimension `position_bucket`, `sentiment_band`, and `rank` are **conditional dimensions** — they describe how an entity appeared in a response, so they only exist on responses where that entity is actually mentioned (and, for `rank`, ranked): * `position_bucket`: `top`, `middle`, `bottom` * `sentiment_band`: `positive`, `mixed`, `negative`, `none` * `rank`: positive integers (`1`, `2`, …), where `1` is the first mention When you group by any of these, responses where the entity is not mentioned (or, for `rank`, not ranked) are excluded from the breakdown — there is no "not mentioned" or "rank 0" row. Alongside a presence metric, each row reports that bucket's **share of mentions**: the buckets within a group sum to 1.0 (100% of mentioned responses), not to the overall mention rate. To relate the shares back to overall visibility, run a second query without the conditional dimension or multiply each share by the overall presence metric. The conditional dimension follows the **entity scope of the metric** it is paired with: * Pair with `brand_*` mention metrics to break out your brand's position, sentiment, or rank distribution. * Pair with `competitor_*` mention metrics (plus a `competitor_id` / `competitor_name` filter) to break out a competitor's distribution. * Pair with `market_*` mention metrics to break out the pooled distribution across every tracked entity. ### Position breakdown ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=position_bucket,brand_presence_percentage" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ```json theme={null} [ { "position_bucket": "top", "brand_presence_percentage": 0.58 }, { "position_bucket": "middle", "brand_presence_percentage": 0.29 }, { "position_bucket": "bottom", "brand_presence_percentage": 0.13 } ] ``` Here 58% of the responses that mention your brand place it in the top of the answer. ### Rank distribution ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=rank,brand_presence_percentage" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ```json theme={null} [ { "rank": 1, "brand_presence_percentage": 0.62 }, { "rank": 2, "brand_presence_percentage": 0.24 }, { "rank": 3, "brand_presence_percentage": 0.10 }, { "rank": 4, "brand_presence_percentage": 0.04 } ] ``` Of all responses that mention your brand, 62% list it first. Pair `rank` with a `competitor_*` mention metric (and a `competitor_id` filter) to chart the same distribution for a competitor, or with a `market_*` mention metric to chart the pooled distribution across every tracked entity. ### Crossing with non-conditional dimensions The same decomposition holds per group when you cross a conditional dimension with a non-conditional one — shares sum to 1.0 within each `ai_platform` below: ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=ai_platform,position_bucket,brand_presence_percentage" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` ### Filtering on a conditional dimension You can also use either dimension purely as a filter — for example, to restrict every other metric in a query to responses where the brand appears in the top of the answer, or only to positive mentions: ```bash theme={null} # Top-of-answer mentions only curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=ai_platform,responses&filters=position_bucket:top" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" # Positive mentions on ChatGPT only curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=ai_platform,responses&filters=sentiment_band:positive&filters=ai_platform:ChatGPT" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` > [!NOTE] > > This behavior only applies when `position_bucket` or `sentiment_band` is in `fields`. For queries that do not group by either, `brand_presence_percentage` keeps its usual meaning — the share of all responses that mention the brand. > [!WARNING] > > A single query cannot mix a brand metric **and** a competitor metric **and** a conditional dimension — one breakdown column can only describe one entity's row. Such requests return `HTTP 400`; split them into separate queries. `having` on a presence metric is also rejected with `HTTP 400` when a conditional dimension is in `fields`; filter on a count metric such as `brand_unique_responses` instead. *** ## Date range and validation Use the `start_date` and `end_date` query parameters to scope a request to a specific window. Both are optional and accept the `YYYY-MM-DD` format. | Behavior | What happens | | - | - | | Both omitted | Returns the last 30 days, ending today (UTC). | | Only `start_date` set | `end_date` defaults to today (UTC). | | Only `end_date` set | `start_date` defaults to 30 days before `end_date`. | | Empty string (`?start_date=`) | Treated as missing. The default applies. | | Trailing or leading whitespace (`?start_date=2026-03-20%20`) | Trimmed before parsing. The cleaned value is used. | | Malformed value (`?start_date=2024-02-30` or `?start_date=tomorrow`) | Returns `HTTP 400` with the offending value in `detail`. | ### Example: valid request ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/query?start_date=2026-03-01&end_date=2026-03-31&fields=date_week,brand_presence_percentage" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` ### Example: invalid date returns 400 ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/query?start_date=2024-02-30" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` ```json theme={null} { "detail": "Invalid start_date '2024-02-30': expected YYYY-MM-DD" } ``` > [!TIP] > > If you build query strings dynamically, prefer omitting `start_date` / `end_date` when you don't have a value rather than passing an empty string — the result is the same, but the intent is clearer. *** ## Cardinality and result size Because the Query API performs grouping dynamically, combining highly granular dimensions can significantly increase the number of rows returned. Examples of high-cardinality dimensions include: * ai_platform * tag * prompt_topic * competitor_id * competitor_name * source_url * source_domain * domain * source_type * query_fanouts Each additional high-cardinality field multiplies the number of possible result rows. > [!WARNING] > > Avoid combining multiple high-cardinality dimensions unless required, as this can produce very large result sets and slower queries. *** ## Limits and performance considerations * The Query API supports large batch pulls (up to tens of thousands of rows per request) * Results are pre-aggregated and optimized for analytics and BI ingestion * Query performance degrades as result cardinality increases For best performance, keep field selections focused and intentional. *** ## Best practices * Prefer date_week or date_month over daily granularity when possible * Run separate queries for different reporting needs and join downstream * Keep field lists small to control result size * Use brand-scoped API keys when embedding in client-facing dashboards * Treat Query API outputs as metrics tables, not raw data logs *** ## Relationship to the Responses API The Query API and Responses API are complementary: * Query API: fast, aggregated metrics for reporting and dashboards * Responses API: full-fidelity response text and citation data for deep analysis Most customers use the Query API for ongoing reporting and the Responses API selectively for audits, research, or investigation. > [card] [Run your first query](/getting-started/quickstart-query) > > Go to the Query API Quickstart → # Structured Query API: Multi-Metric JSON Endpoint Source: https://developers.scrunch.com/api-reference/query/structured-query POST brand-scoped JSON queries with dimensions, metrics, HAVING thresholds, negated filters, and prior-period or prior-year comparisons. ## Overview The structured query endpoint accepts a JSON request body describing the dimensions, metrics, filters, and comparisons you want, and returns a columnar result. Use it when you need richer query shapes than the [GET query endpoint](/api-reference/query/overview) supports — for example, post-aggregation thresholds, negated filters, or period-over-period comparison in a single round trip. ```http theme={null} POST https://api.scrunchai.com/v2/query/{brand_id} ``` The structured endpoint and the `GET` endpoint share the same dimensions, metrics, and brand scoping. They differ in expressivity and request shape: the structured endpoint takes a JSON body and adds `having`, `negate`, and `comparison`. *** ## When to use Use the structured endpoint when you need to: * Filter on metric thresholds after aggregation (for example, only weeks with at least 10 responses). * Exclude a set of values rather than include them (`negate: true`). * Pull a current-period result and a prior-period result in one request, aligned for charting. * Submit complex filter combinations that are awkward to encode in URL parameters. For straightforward dimension-and-metric pulls, the [GET query endpoint](/api-reference/query/overview) remains the simpler choice. *** ## Authentication Authenticate with a Bearer API key. The key must include the **Query** scope and have access to the target brand. See [Provision an API Key](/getting-started/authentication). ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/query/$SCRUNCH_BRAND_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d @query.json ``` *** ## Request body | Field | Type | Required | Description | | - | - | - | - | | `fields` | `string[]` | Yes | Dimensions and metrics to return. 1–32 entries. See [Fields reference](/api-reference/query/overview#fields-reference). | | `start_date` | `string` (YYYY-MM-DD) | No | Inclusive start. Defaults to 30 days ago. Required when `comparison` is set. | | `end_date` | `string` (YYYY-MM-DD) | No | Inclusive end. Defaults to today. Required when `comparison` is set. | | `filters` | `DimensionFilter[]` | No | Pre-aggregation `WHERE` filters on dimensions. Up to 25 entries. | | `having` | `HavingFilter[]` | No | Post-aggregation `HAVING` filters on metrics. Up to 10 entries. | | `comparison` | `Comparison` | No | Period-over-period comparison configuration. | | `include_totals` | `boolean` | No | Compute a grand total over the full result set and return it in `totals`. When the returned rows are a proper subset of the total (a top-N breakdown), the response also carries a derived `"other"` remainder. Default `false`. Rejected in combination with `comparison`. See [Totals and remainder](#totals-and-remainder). | | `include_row_count` | `boolean` | No | Populate `pagination.total_rows` with the number of grouped rows the query matched before `limit`. Off by default because it re-runs the aggregation and can cost roughly as much as the row query itself. Ask for it only to render a "showing N of M" caption. Paging does not need it — `pagination.has_more` is exact and free. Default `false`. | | `limit` | `integer` | No | Row cap. Default `50000`, maximum `90000`. | | `offset` | `integer` | No | Row offset for pagination. Default `0`. | ### DimensionFilter ```json theme={null} { "field": "ai_platform", "values": ["ChatGPT"], "negate": false } ``` | Field | Type | Description | | - | - | - | | `field` | string | A filterable dimension. `prompt` is not filterable. | | `values` | array | One or more values to match. Up to 1000 entries. Values are coerced to the dimension's type — booleans accept `true`/`false`, `1`/`0`, `"true"`/`"false"`, `"yes"`/`"no"`; integer dimensions accept numeric strings. Mismatched types return HTTP `422`. Pass the reserved token `"__none__"` on `tag` or `prompt_topic` to match prompts that carry no tag or no topic. See [Filter for prompts with no tag or topic](#filter-for-prompts-with-no-tag-or-topic). | | `negate` | boolean | When `true`, excludes rows that match. With `match: "all"`, this excludes prompts carrying every specified value; it does not exclude prompts carrying only some of them. Default `false`. | | `match` | enum | How multiple `values` combine. `"any"` (default) matches prompts carrying at least one value (OR). `"all"` matches only prompts carrying every value (AND). Only supported on the array-valued prompt dimensions `tag` and `prompt_topic`; sending `"all"` on any other field returns HTTP `422`. | #### Match modes By default, multi-value filters combine with OR — a filter on `tag` with `["A", "B"]` returns prompts tagged **A or B**. This widens the result set as you add values. Set `match: "all"` on `tag` or `prompt_topic` to combine with AND instead — the filter then returns only prompts tagged **A and B**, narrowing the result set. Use this when a prompt can carry multiple tags or topics and you want to isolate the intersection (for example, product-level reporting that requires two tags at once). `match` only applies to `tag` and `prompt_topic`, which map each prompt to a set of values. Scalar dimensions like `ai_platform` or `country` reject `match: "all"` with HTTP `422` — a row has one platform, so AND across values would match nothing. Omit `match` (or send `"any"`) on scalar dimensions. #### Filter and group by the same tag or topic A prompt can carry several tags and topics. When you filter on `tag` or `prompt_topic` and also include that dimension in `fields`, Scrunch returns rows only for the values you filtered on. Other tags or topics that the matching prompts also carry don't appear as rows. ```json theme={null} { "fields": ["prompt_topic", "brand_presence_percentage"], "filters": [ { "field": "prompt_topic", "values": ["Pricing", "Support"] } ] } ``` This request returns one row for `Pricing` and one row for `Support`. Each row covers the prompts that carry that topic. * **`match: "all"`**: every matching prompt carries all the selected values, so Scrunch returns one row. That row is labeled with the first value in `values`. In the example above, `match: "all"` returns a single `Pricing` row that covers prompts carrying both `Pricing` and `Support`. * **`"__none__"`**: the filter keeps a row for prompts with no tag or topic. In that row, the dimension value is `null`. * **Several filters on the same field**: Scrunch returns rows for every value named across the non-negated filters on that field. * **`negate: true`**: a negated filter narrows the prompts but adds no rows. #### Filtering by citation segment `citation_segment_id` is filter-only: pass segment ids in `values` to scope citation metrics to specific segments. It cannot appear in `fields` — break results down by segment name with the `citation_segment` dimension instead. Segment ids are brand-scoped; an id that does not belong to the brand returns HTTP `400`. Each segment filters by its configured match mode. Prefix segments (the default) match their entries and any subpath. Exact segments match only the listed pages, ignoring letter case, `www.`, ports, query strings, and trailing slashes. Managed **Agent Pages** segments resolve to the pages their AXP site is serving right now, so the filter tracks deployments automatically. Pass multiple ids to combine sites — for example, a `www` site and a docs subdomain that the `domain` filter cannot separate. A managed segment whose site currently serves no pages matches zero rows. ```json theme={null} { "fields": ["date_week", "citation_count", "citation_unique_responses"], "filters": [ { "field": "citation_segment_id", "values": [123, 456] } ] } ``` #### Filtering by citation source owner `owner` accepts a closed vocabulary — `brand`, `competitor`, `other`. Any other value returns `HTTP 422`. Without a source-grain breakdown (`domain`, `source_url`, `citation_segment`, `source_topic`) in `fields`, the filter keeps whole responses that cite at least one source of that owner; with one, it narrows the source-grain rows to the matching sources only. The filter must be paired with a citation metric — see the GET endpoint's [Filtering by citation source owner](/api-reference/query/overview#filtering-by-citation-source-owner) for the full rules. ```json theme={null} { "fields": ["domain", "citation_count", "brand_citation_mention_rate"], "filters": [ { "field": "owner", "values": ["competitor"] } ] } ``` ### HavingFilter ```json theme={null} { "metric": "responses", "operator": "gte", "value": 10 } ``` | Field | Type | Description | | - | - | - | | `metric` | string | A metric in `fields`. Referencing a metric not in `fields` is an error. | | `operator` | enum | One of `gt`, `gte`, `lt`, `lte`, `eq`, `neq`. | | `value` | number | The threshold. `inf` and `nan` are rejected. | ### Comparison ```json theme={null} { "mode": "prior_period" } ``` | Field | Type | Description | | - | - | - | | `mode` | enum | `prior_period` shifts back by the window length. `prior_year` shifts back by one calendar year (Feb 29 falls back to Feb 28 in non-leap years). | When `comparison` is set, `start_date` and `end_date` are required and the response includes a synthetic `period` dimension with values `current` and `prior`. Each period is capped at `limit / 2` rows so the merged result stays within `limit`. Prior-period dates are aligned to current-period bucket labels so the two series overlay on a chart. *** ## Response The response is columnar. ```jsonc theme={null} { "columns": [ { "name": "date_week", "kind": "dimension", "dtype": "date", "rollup": null }, { "name": "brand_presence_percentage", "kind": "metric", "dtype": "float", "rollup": "ratio" } ], "rows": [ ["2026-W14", 0.421], ["2026-W15", 0.478] ], "pagination": { "limit": 50000, "offset": 0, "has_more": false, "total_rows": null }, "totals": null, "compare_status": null } ``` | Field | Type | Description | | - | - | - | | `columns` | array | Column metadata in the same order as `rows`. `kind` is `dimension` or `metric`. `dtype` is one of `string`, `int`, `float`, `bool`, `date`. | | `columns[].rollup` | `"count"` \| `"ratio"` \| `"average"` \| `"none"` \| `null` | On metric columns, how per-row values collapse into one window-level number. `null` on dimensions. See [Rolling up metrics client-side](#rolling-up-metrics-client-side). | | `rows` | array | Each row has one cell per column. | | `pagination.limit` | integer | The row cap clients should use for end-of-page detection. Echoes `limit` for non-comparison queries and for successful comparison queries (each period is capped at `limit / 2` rows, and the merged result never exceeds `limit`). When `compare_status` is `"current_only"`, returns `limit / 2` — the cap that was actually applied to the surviving current series. | | `pagination.offset` | integer | Echoes the requested offset. | | `pagination.has_more` | boolean | `true` when the query matched more rows than `limit` returned. Determined exactly (the server asks ClickHouse for `limit + 1` rows and drops the extra one), so `len(rows) == limit` is not a reliable substitute. Always present. | | `pagination.total_rows` | integer \| null | Total grouped rows matched, ignoring `limit` and `offset`. Populated when the request set `include_row_count: true`; `null` otherwise. | | `totals` | object \| null | The window's grand total. Populated when the request set `include_totals: true`; `null` otherwise. See [Totals and remainder](#totals-and-remainder). | | `compare_status` | `"current_only"` \| `null` | Set to `"current_only"` when `comparison` was requested but the prior-period query failed; the response then contains only the current series. `null` otherwise. | Date dimensions are formatted as labels: `date` → `YYYY-MM-DD`, `date_week` → ISO `YYYY-Www` (uses ISO week-numbering year, so dates near the year boundary group with their ISO week — for example, `2024-12-30` is `2025-W01`), `date_month` → `YYYY-MM`, `date_quarter` → `YYYY-Q#`, `date_year` → `YYYY`. ### Totals and remainder Set `include_totals: true` to receive a `totals` object alongside `rows`. The server computes the grand total in SQL over the full result set, so it does not drift when `limit` truncates the rows or when a top-N request excludes long-tail slices. ```jsonc theme={null} "totals": { "values": [null, 0.312], "remainder": [null, 0.284] } ``` | Field | Type | Description | | - | - | - | | `values` | array | One cell per column, positionally aligned with `columns`. Dimension positions are `null`; metric positions carry the window-level aggregate. | | `remainder` | array \| null | The `"other"` bucket — the total minus what the returned rows account for, derived from the parts. `null` when the returned rows overlap and no honest leftover exists (for example, tag-sliced rows that share responses). Populated only alongside a limited breakdown result. | Use `totals.values` to render an accurate percentage-of-total on a page that shows only a top-N slice, and `totals.remainder` to display a real "Other" slice in a donut or pie without querying the tail separately. `include_totals` is rejected in combination with `comparison`: the response interleaves two periods, so a single grand total describes neither. Request the two periods separately. ### Rolling up metrics client-side Every metric column carries a `rollup` mode that tells you how to collapse its per-row values into one window-level number — the arithmetic the server would perform if you re-queried without the axis you are flattening. Use it when you fold a time-bucketed or breakdown-sliced response down to a single value in the client. | Mode | Meaning | | - | - | | `count` | Additive. Sum the values across rows. | | `ratio` | A poolable rate. Recover the window value as `sum(numerator) / sum(denominator)` — request `metric_shape: "envelope"` to get the numerator and denominator per row. | | `average` | A poolable average. Recover the window value as `sum(value * denominator) / sum(denominator)` — request `metric_shape: "envelope"` for the denominators. | | `none` | Not poolable. No arithmetic over the returned rows recovers the window value. Re-query without the collapsing dimension to get the true total. | Averaging or summing without following the declared `rollup` gives measurably wrong window-level numbers on rate and average metrics — an unweighted mean of per-day rates weights a 1-response day the same as a 4,000-response day. When you only need the window aggregate and do not care about the per-row values, set `include_totals: true` instead and read `totals.values`. *** ## Examples ### Multi-metric weekly trend with a platform filter ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/query/$SCRUNCH_BRAND_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2026-04-01", "end_date": "2026-04-30", "fields": ["date_week", "brand_presence_percentage", "brand_unique_prompts"], "filters": [ { "field": "ai_platform", "values": ["ChatGPT"] } ] }' ``` ### Threshold the result with HAVING Return only weeks that received at least 10 responses. ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/query/$SCRUNCH_BRAND_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2026-04-01", "end_date": "2026-04-30", "fields": ["date_week", "responses", "brand_presence_percentage"], "having": [ { "metric": "responses", "operator": "gte", "value": 10 } ] }' ``` ### Period-over-period comparison ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/query/$SCRUNCH_BRAND_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2026-04-01", "end_date": "2026-04-30", "fields": ["date_week", "brand_presence_percentage"], "comparison": { "mode": "prior_period" } }' ``` The response prepends a `period` column. Prior dates are mapped to current-period labels so the series can be plotted on a single x-axis. ### Exclude specific prompts ```json theme={null} { "fields": ["prompt_topic", "responses"], "filters": [ { "field": "prompt_topic", "values": ["Pricing", "Support"], "negate": true } ] } ``` ### Match all tags (AND) instead of any (OR) Return only prompts carrying **both** tags. Without `match: "all"`, this filter returns prompts carrying **either** tag. ```json theme={null} { "fields": ["brand_presence_percentage"], "filters": [ { "field": "tag", "values": ["Enterprise", "Security"], "match": "all" } ] } ``` ### Filter for prompts with no tag or topic Pass the reserved token `"__none__"` in `values` on a `tag` or `prompt_topic` filter to match prompts that carry no tag or no topic. Use it to isolate the untagged tail of your prompt set — for example, to audit coverage gaps or to compute presence on the unclassified slice. Only `tag` and `prompt_topic` accept `"__none__"`. Sending it on any other dimension returns HTTP `422`. Return only untagged prompts: ```json theme={null} { "fields": ["brand_presence_percentage"], "filters": [ { "field": "tag", "values": ["__none__"] } ] } ``` Combine `"__none__"` with real values in the same filter — the filter matches either the untagged prompts **or** the named tags: ```json theme={null} { "fields": ["tag", "brand_presence_percentage"], "filters": [ { "field": "tag", "values": ["__none__", "Core"] } ] } ``` Set `negate: true` to invert the whole filter — for example, prompts that carry at least one tag: ```json theme={null} { "fields": ["brand_presence_percentage"], "filters": [ { "field": "tag", "values": ["__none__"], "negate": true } ] } ``` `"__none__"` cannot combine with `match: "all"`: the request returns HTTP `422`. A prompt with no tag has an empty tag set, so requiring it to contain "every" value including `"__none__"` is contradictory. Keep `match` as the default `"any"` (OR) when the filter uses `"__none__"`. A tag literally named `__none__` becomes unreachable by equality — the token always resolves to the absence match. Rename such a tag if you need to filter for it directly. ### Top slices with a grand total and "other" remainder Request the top platforms for a metric alongside the full-window total. `totals.values` gives the accurate window-level number, and `totals.remainder` accounts for everything past the returned rows. ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/query/$SCRUNCH_BRAND_ID" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2026-04-01", "end_date": "2026-04-30", "fields": ["ai_platform", "brand_presence_percentage"], "limit": 5, "include_totals": true }' ``` *** ## Limits | Limit | Value | | - | - | | Fields per request | 32 | | Filters per request | 25 | | HAVING clauses per request | 10 | | Values per filter | 1000 | | Rows per response (`limit`) | 90000 | | Default rows per response | 50000 | | Server-side execution time | 30 seconds | Requests that exceed these limits are rejected with HTTP `422`. *** ## Errors | Status | Cause | | - | - | | `401` | Missing or invalid API key. | | `403` | API key lacks the `query` scope or access to the brand. | | `400` | The field combination cannot be built into a single query — for example, citation metrics combined with raw-path-only fields, or a share-of-voice metric with an unsupported breakdown. Also returned for an unknown `citation_segment_id` filter value. | | `404` | Brand not found. | | `422` | Request body fails validation (for example, a non-filterable dimension in `filters`, a HAVING metric not in `fields`, `start_date` after `end_date`, a value that cannot be coerced to the dimension's type, a HAVING `value` of `inf` or `nan`, `match: "all"` on a dimension other than `tag` or `prompt_topic`, `"__none__"` on a dimension other than `tag` or `prompt_topic`, `"__none__"` combined with `match: "all"`, `include_totals: true` combined with `comparison`, or a request that exceeds the size limits). | | `500` | Server error. When triggered by the prior-period query in a comparison request, the response succeeds with `compare_status: "current_only"` instead. | *** ## Related > [card] [Query API overview](/api-reference/query/overview) > > Field reference shared with the `GET` endpoint. > [card] [Query API quickstart](/getting-started/quickstart-query) > > First request walkthrough. # Responses API: Raw AI Answers and Citations Source: https://developers.scrunch.com/api-reference/responses/overview Retrieve every raw AI response Scrunch collects with full text, citations, sentiment, competitor evaluations, persona, and platform metadata. ## Overview The Responses API provides row-level access to the full AI responses captured by Scrunch. Each record represents a single AI-generated answer observed on a supported platform and includes the complete response text, citation metadata, and brand and competitor evaluations. This API is designed for teams that need maximum fidelity into how AI platforms answer questions about their category, brand, and competitors. Typical use cases include ETL pipelines, research workflows, full-text analysis, citation audits, internal tooling, and advanced modeling. *** ## What the Responses API includes Each response record may include: * Full AI response text (markdown) * Citations, including URL, domain, snippet, title, and source type * Brand presence, sentiment, and position * Competitor presence, sentiment, and position * Prompt metadata (persona, tags, key topics, stage) * Platform, country, and collection timestamp * Query fan-out — the searches the platform ran internally, where exposed * Shopping results, where the platform surfaced product listings Each item corresponds to one AI response, not an aggregate or summary. *** ## When to use the Responses API Choose the Responses API if you need: * Per-response visibility instead of averages * The exact text produced by AI platforms * Citation-level analysis and influence modeling * Competitor comparisons within individual responses * Custom pipelines or internal UIs built on raw AI output * Daily or periodic ingestion jobs using high watermarks This API is intentionally verbose and optimized for depth and accuracy rather than aggregation. *** ## When not to use the Responses API The Responses API is not ideal if you only need: * Aggregated metrics (presence percentage, position score, sentiment score) * Lightweight dashboards or BI reporting * Trend analysis over time without response text For those use cases, the Query API is more efficient and better suited. *** ## Data mutability and re-evaluation Not all fields behave the same over time. Immutable fields: * response_text * citations * created_at * query_fanout, shopping_results These reflect exactly what was observed at the time the response was captured. Fields that may be re-evaluated: * stage, tags, key_topics * brand_present, brand_sentiment, brand_position * competitors and competitors_present evaluation fields These may change if prompt metadata is edited in the Scrunch UI or if brand configuration is updated and re-evaluation is requested. For ETL workflows, always deduplicate or upsert using the globally unique id. *** ## Which prompts' responses are returned The prompt's own status is the only filter on historical responses: * Responses from **active** and **paused** prompts are returned. * Responses from **archived** prompts are excluded. * Persona state does not affect visibility. Archiving a persona no longer hides responses from its still-active prompts, so response counts match the prompts you see in Prompt Templates. > [!WARNING] > > `id`, `prompt_id`, `persona_id`, and each competitor's `id` are **64-bit integers**, not strings. Response IDs are already nine digits, so parsers that coerce large integers into a 32-bit int or a JavaScript `Number` past 2^53 will corrupt them. Type these columns as `INT64` / `BIGINT` downstream. *** ## Request parameters All parameters are optional. | Parameter | Type | Description | Notes | | - | - | - | - | | `platform` | String (Enum) | AI platform to retrieve responses for | Valid values: `chatgpt`, `claude`, `google_ai_overviews`, `perplexity`, `meta`, `google_ai_mode`, `google_gemini`, `copilot`, `grok` | | `prompt_id` | Number | Specific prompt ID to retrieve responses for | | | `persona_id` | Number | Specific persona ID to retrieve responses for | | | `stage` | String | Customer journey stage to filter by | The stage **name**, resolved against the brand's configured stages — not a fixed enum. See `stage` under Response below | | `start_date` | Date (`YYYY-MM-DD`) | Start date of responses to retrieve | Inclusive | | `end_date` | Date (`YYYY-MM-DD`) | End date of responses to retrieve | **Exclusive** — to fetch a single day, set this to the following day | | `has_shopping_data` | Boolean | Filter by presence of shopping results | `true` returns only responses with shopping results, `false` only those without. Omit for no filter | | `limit` | Number | Maximum number of responses to return per page | Minimum 1, defaults to 100. No maximum is enforced — values well above 1000 are honored — but 1000 is a sensible page size for reliable, resumable jobs | | `offset` | Number | Offset for pagination | Should be a multiple of `limit` | For incremental ingestion: 1. Pull responses using a date window 2. Store the `created_at` value from the latest record 3. Use that internally as a high watermark 4. Or load the previous UTC day after midnight to ensure completeness *** ## Denormalized response model Each API item represents a single response with related data embedded as arrays. * citations * tags * key_topics * competitors * shopping_results The API does not fan out rows for many-to-many relationships. If you are building dimensional tables or star schemas, you will need to normalize these arrays downstream. This differs intentionally from the Query API, which performs aggregation and grouping. *** ## Response schema ### Collection Responses use Scrunch's standard paginated collection format. | Field | Type | Description | Notes | | - | - | - | - | | `total` | Number | Total number of responses available for the current parameters | | | `offset` | Number | Current offset retrieved | Add `limit` to this value to retrieve the next page | | `limit` | Number | Limit applied to the current request | | | `items` | `Response[]` | List of Response objects | See below | To retrieve the next page: ``` offset = offset + limit ``` For stable ETL jobs, ensure offset increments in multiples of `limit`. ### Response | Field | Type | Description | Notes | | - | - | - | - | | `id` | Number | Unique ID for the response | Responses are immutable in normal operations — safe to deduplicate or upsert on `id` | | `created_at` | Timestamp (UTC) | Granular timestamp the response was collected at | | | `prompt_id` | Number | Unique ID for the prompt | Can be retrieved from the Prompts API | | `prompt` | String | Prompt text | | | `persona_id` | Number (Nullable) | Persona ID attached to the prompt | | | `persona_name` | String (Nullable) | Persona name attached to the prompt | | | `country` | String (Nullable) | 2-character ISO country code the response was retrieved for | | | `stage` | String | Stage of the customer journey the prompt is mapped to. Values are resolved from your brand's configured stages, so they vary per brand. Default sets: intent — `Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other`; funnel — `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other`. Brands that rename or add stages return those custom names. | | | `tags` | String\[] | Tags attached to the prompt | | | `key_topics` | String\[] | Key topics attached to the prompt | | | `platform` | String (Enum) | AI platform the response was retrieved from | See platform values under Request Parameters | | `brand_present` | Boolean | Whether the brand is present in the response | | | `brand_sentiment` | String (Enum) (Nullable) | Sentiment toward the brand | Null when brand not present. Values: `positive`, `mixed`, `negative`, `none` | | `brand_position` | String (Enum) (Nullable) | Position of the brand within the response | Null when brand not present. Values: `top`, `middle`, `bottom` | | `competitors_present` | String\[] | List of competitor names found in the response | | | `response_text` | String | Full AI-generated response text | Markdown format | | `citations` | `Citation[]` | Citations included in the response | See Citation below | | `competitors` | `CompetitorEvaluation[]` | Per-competitor evaluation data | Same set of competitors as `competitors_present`, with position and sentiment added. Contains **only competitors mentioned in the response** — empty when none were. See CompetitorEvaluation below | | `query_fanout` | Object (Nullable) | Search queries the AI platform generated internally while answering | `{ "queries": String[], "engine_metadata": Object }`. Null on platforms that do not expose fan-out, which is most rows | | `shopping_results` | `ShoppingResult[]` | Product listings surfaced in the response | Empty for most responses. Filter with `has_shopping_data`. See ShoppingResult below | > [!WARNING] > > Enum values are returned **lowercase** — `positive`, `top`, `brand`, `chatgpt`. A `CASE` expression or mapping written against capitalized values (`Positive`, `Top`) will match nothing and silently yield nulls rather than an error. The exceptions are `stage` and `key_topics`, which are returned as display-cased names. > [!NOTE] > > `brand_sentiment` has four values, and `none` is not the same as `null`. `none` means the brand was mentioned but with no discernible sentiment; `null` means the brand was not mentioned at all. Scrunch's own sentiment score excludes `none` from the average rather than scoring it as neutral. ### Citation | Field | Type | Description | Notes | | - | - | - | - | | `url` | String | URL of the citation | | | `title` | String (Nullable) | Title tag of the citation | Not exposed by all platforms, and typically returned as an **empty string** rather than null when absent — test with `NULLIF(title, '')` rather than `IS NOT NULL` | | `snippet` | String (Nullable) | Search engine snippet for the citation | Often but not always from the meta description tag. Not exposed by all platforms | | `source_type` | String (Enum) | Classification of the citation source | `brand`, `competitor`, `other` — "other" corresponds to third-party in the Scrunch UI | | `domain` | String | Registered domain extracted from the URL | Provided for convenience | ### CompetitorEvaluation | Field | Type | Description | Notes | | - | - | - | - | | `name` | String | Name of the competitor | Editable in the Scrunch UI — join on `id`, not `name` | | `id` | Number | Unique ID for the competitor | Stable join key | | `present` | Boolean | Whether the competitor is present in the response | Always `true` — the array only contains mentioned competitors | | `position` | String (Enum) (Nullable) | Position of the competitor within the response | Values: `top`, `middle`, `bottom` | | `sentiment` | String (Enum) (Nullable) | Sentiment toward the competitor | Values: `positive`, `mixed`, `negative`, `none` | > [!WARNING] > > The `competitors` array is **not** a row per configured competitor — it lists only the competitors mentioned in that response, and is empty when none were. It therefore cannot supply a denominator for competitor presence rate: divide by the total response count instead. See [Computing metrics](/guides/data-mart-loading#competitor-metrics) in the data mart guide. ### ShoppingResult Present only on responses where the platform surfaced product listings. | Field | Type | Description | Notes | | - | - | - | - | | `url` | String | URL of the shopping result | | | `title` | String | Title of the shopping result | | | `image` | String (Nullable) | Primary product image | | | `all_images` | String\[] (Nullable) | All product images | | | `description` | String (Nullable) | Product description | | | `rating` | Number (Nullable) | Product rating | | | `reviews` | Number (Nullable) | Review count | | | `purchasing_options` | Object\[] (Nullable) | Seller and price options for the product | | *** ## ETL recommended workflow 1. Start with `start_date` (UTC) 2. Pull responses in batches (`limit=1000`) 3. Store `created_at` from the last record 4. Use that as the new start date for your next batch 5. Deduplicate using `id` (globally unique) ## Typical downstream uses Customers commonly use the Responses API to: * Audit AI hallucinations or brand misrepresentation * Analyze which third-party sources influence AI answers * Train internal RAG or evaluation systems * Perform NLP or sentiment analysis across competitors * Build internal review tools for AI output quality * Support custom reporting or research workflows > [card] [Get started with Responses](/getting-started/quickstart-responses) > > Responses API Quickstart → # Clear Signal Reaction Source: https://developers.scrunch.com/api-reference/signals/clear-signal-reaction /api-reference/openapi.json delete /{brand_id}/signals/{signal_id}/reaction Remove the calling user's reaction on a signal's stable identity. Requires a **user token** (JWT); API keys receive 403. # Get Signal Source: https://developers.scrunch.com/api-reference/signals/get-signal /api-reference/openapi.json get /{brand_id}/signals/{signal_id} Fetch one signal by ID, including its full narrative (what happened, why it matters, what to do) when available. Returns 404 for IDs that exist but are not user-facing (non-fired or cluster-child rows) — the same population rule as `listSignals`. # List Signal Anchor Dates Source: https://developers.scrunch.com/api-reference/signals/list-signal-anchor-dates /api-reference/openapi.json get /{brand_id}/signals/anchors List recent distinct detection dates (`detected_for_date`) that produced user-facing signals, newest first. Useful for building date pickers or polling for new detection runs — the population matches `listSignals` with default filters, so every returned day has at least one signal. # List Signal Reactions Source: https://developers.scrunch.com/api-reference/signals/list-signal-reactions /api-reference/openapi.json get /{brand_id}/signals/reactions List reactions users have set on this brand's signals, newest first. This is **brand-wide** — it returns every user's reactions, not just the caller's — so an integration can export the team's aggregate feedback. Filter by `fingerprint` to get reactions for one signal identity, or by `reaction` to get e.g. everything marked `useful`. # List Signals Source: https://developers.scrunch.com/api-reference/signals/list-signals /api-reference/openapi.json get /{brand_id}/signals List detected signals for a brand — statistically-tested movements (level changes and trends) in AI-visibility metrics, produced by the nightly detection sweep. ## Population By default only user-facing signals are returned: the confidence tiers `high`, `confident`, `worth_a_look`, and `provisional`. Pass an explicit `tier` to select a single tier, including the noise-floor tiers. An ongoing signal is re-detected daily under the same `fingerprint`; a multi-day date range returns only the latest detection per signal identity, so you never see day-by-day duplicates of the same issue. ## Tracking one issue over time A signal's `fingerprint` is its durable identity: it survives nightly re-detections *and* direction flips of the same underlying issue. To follow an issue after remediation, filter by `fingerprint` with a wide `anchor_from` — a later detection in the opposite `direction` on the same fingerprint is the recovery (or regression) of the original movement. Combine with `direction` to fetch each side separately. ## Sorting `sort=score_desc` (default) orders by engine priority, `delta_desc` by largest absolute change, `detected_desc` by newest detection date. # Signals API: Detected changes in AI visibility Source: https://developers.scrunch.com/api-reference/signals/overview Query Scrunch's nightly detection sweep for statistically-tested level changes and trends in AI visibility metrics, with stable signal identity. ## Overview The Signals API exposes Scrunch's nightly detection sweep as a queryable feed. Each **signal** is a statistically-tested movement — a level change or trend — in one of your brand's AI visibility metrics on a specific slice of your data (a platform, topic, or the account as a whole). Use it to feed alerts into your own tools, drive weekly briefs, or automate follow-up on the same "what changed" events surfaced in the Scrunch dashboard. *** ## What the Signals API includes * Detected level changes and trends on core metrics (`presence_rate`, `position_top_rate`, `cited_domain_rate`) * A confidence tier for each signal (`high`, `confident`, `worth_a_look`, `provisional`), with noise-floor tiers available on request * Human-readable narrative: what happened, why it matters, and what to do * A **stable fingerprint** for each underlying issue — the same signal keeps its fingerprint across nightly re-detections, so reactions and downstream state survive * Reactions (`useful`, `not_useful`, `dismissed`, `actioned`) with optional free-text reasons, listable brand-wide for team-level reporting * Anchor dates (distinct detection days) for building date pickers and polling loops Signals are dedup-to-latest per identity: over a multi-day range you see one row per underlying issue, not one row per re-detection. *** ## When to use the Signals API Use the Signals API when you need to: * Post "what changed this week" summaries to Slack, email, or a stakeholder digest * Route detected drops on a specific platform, topic, or metric into an incident tracker * Export the team's reactions on signals for reporting or feedback loops * Build a custom alerting dashboard that mirrors the Scrunch Signals feed For ad-hoc "how is metric X trending" questions, use the [Query API](/api-reference/query/overview) — Signals only surfaces movements that pass detection thresholds. *** ## Endpoints | Method | Path | Purpose | | - | - | - | | GET | `/{brand_id}/signals` | List detected signals with filters. | | GET | `/{brand_id}/signals/{signal_id}` | Get one signal with its full narrative. | | GET | `/{brand_id}/signals/anchors` | List recent detection dates that produced signals. | | GET | `/{brand_id}/signals/reactions` | List reactions across the brand's signals. | | PUT | `/{brand_id}/signals/{signal_id}/reaction` | Set (or replace) the caller's reaction on a signal. | | DELETE | `/{brand_id}/signals/{signal_id}/reaction` | Clear the caller's reaction. | All endpoints require a bearer token with the `query` scope. Reaction writes additionally require a **user token (JWT)** — API keys have no user identity to attribute a reaction to and receive `403`. See [Authentication](/getting-started/authentication). *** ## Filters The list endpoint accepts: | Filter | Description | | - | - | | `scope` | Slice granularity: `account`, `account_platform`, `topic`, or `topic_platform`. | | `platform` | AI platform (e.g. `OpenAI`). Multi-platform signals carry the `(multi)` sentinel; the response `slice.platforms` lists the real platforms. | | `metric` | Metric the signal fired on (`presence_rate`, `position_top_rate`, `cited_domain_rate`). | | `alert_type` | `level_change` (step shift), `trend` (sustained drift), or `level` (standing in the current window alone, with no baseline). See [Level signals](#level-signals). | | `direction` | `up`, `down`, or `none`. | | `subject_kind` | `brand` or `competitor`. | | `tier` | Restrict to a single confidence tier. Omitting it returns the default user-facing tiers (`high`, `confident`, `worth_a_look`, `provisional`); pass an explicit tier to include noise-floor tiers (`low_confidence`, `underpowered`, `untested`). | | `anchor_from` / `anchor_to` | Inclusive `detected_for_date` bounds (`YYYY-MM-DD`). | | `fingerprint` | Exact match on a signal's stable identity. A fingerprint survives nightly re-detections and direction flips of the same underlying issue, so filtering on one with a wide `anchor_from` tracks how that issue evolved after remediation. Combine with `direction` to fetch the original movement and its recovery separately. 1–128 characters. | | `mover_url` | Case-insensitive substring matched against the URLs in each signal's `url_movers` (per-URL citation movers, emitted for `cited_domain_rate` signals). Only signals with at least one matching mover URL are returned; signals without URL movers never match. `%` and `_` are matched literally. 1–2048 characters. | | `sort` | `score_desc` (default — engine priority), `delta_desc` (largest absolute change), or `detected_desc` (newest detection). | | `limit` / `offset` | Page size (default `50`, max `200`) and offset. | The reactions list endpoint supports `fingerprint` (all reactions on one signal identity) and `reaction` (all reactions of a given value). *** ## Example: list recent high-confidence signals ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/signals?tier=high&sort=detected_desc&limit=20" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` **Response:** ```json theme={null} { "total": 4, "offset": 0, "limit": 20, "items": [ { "id": 90211, "detected_for_date": "2026-07-14", "fingerprint": "b1e0c7a4f9e5...", "subject_kind": "brand", "alert_type": "level_change", "scope": "account_platform", "metric": "presence_rate", "platform": "OpenAI", "direction": "down", "tier": "high", "current_value": 0.31, "baseline_value": 0.47, "delta_absolute": -0.16, "score": 0.82, "narrative_what": "Brand presence on OpenAI dropped 16 pts week-over-week.", "narrative": { "what_happened": "Presence on OpenAI fell from 47% to 31% over the last 7 days.", "why_it_matters": "OpenAI drives the largest share of your tracked AI traffic.", "what_to_do": "Investigate top prompts where the brand disappeared and check citation coverage." }, "slice": { "platforms": ["OpenAI"], "topic_labels": [], "geo_country": null }, "window_current_start": "2026-07-08", "window_current_end": "2026-07-14", "baseline_definition": "Previous 28 days", "url_movers": [], "created_at": "2026-07-15T02:14:00Z" } ] } ``` *** ## Example: get one signal's full narrative ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/signals/90211" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` `getSignal` returns `404` for IDs that exist but aren't user-facing (non-fired detections or cluster-child rows) — the same population rule as the list endpoint. *** ## Example: react to a signal Reactions are keyed on the signal's stable `fingerprint`, so a thumbs-up survives the nightly re-detection of the same underlying issue. This call requires a **user token (JWT)**. ```bash theme={null} curl -X PUT \ "https://api.scrunchai.com/v1/1234/signals/90211/reaction" \ -H "Authorization: Bearer $SCRUNCH_USER_JWT" \ -H "Content-Type: application/json" \ -d '{ "reaction": "actioned", "reason": "Filed ticket ENG-4421." }' ``` ```json theme={null} { "user_id": 55, "insight_id": 90211, "fingerprint": "b1e0c7a4f9e5...", "reaction": "actioned", "reason": "Filed ticket ENG-4421.", "surface": "api", "created_at": "2026-07-15T09:02:11Z", "updated_at": "2026-07-15T09:02:11Z" } ``` Clear a reaction with `DELETE /v1/{brand_id}/signals/{signal_id}/reaction`. *** ## Example: list team reactions The reactions list is **brand-wide** — it returns every user's reactions, not just the caller's — so an integration can export the team's aggregate feedback. ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/signals/reactions?reaction=useful&limit=100" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` Filter by `fingerprint` to pull every reaction on one signal identity across re-detections. *** ## Example: poll for new detection dates ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/signals/anchors?limit=14" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` ```json theme={null} { "dates": ["2026-07-14", "2026-07-13", "2026-07-12"] } ``` Every returned date has at least one user-facing signal. Use it to drive a date picker or as a cheap check before pulling the full list. *** ## URL movers on citation signals For `cited_domain_rate` signals, each response includes a `url_movers` array — the per-URL citation movers behind the movement. Each mover carries: | Field | Description | | - | - | | `normalized_url` | Cited URL with scheme and tracking params stripped. | | `owner` | `brand` (your site) or `competitor`. | | `competitor_id` / `competitor_name` | Set on `competitor`-owned URLs. | | `current_responses` / `baseline_responses` | Distinct AI responses citing the URL in the current and baseline windows. | | `current_prompts` / `baseline_prompts` | Distinct prompts behind those responses. | | `contribution` | Exact share of the signal's metric delta attributed to the URL. Brand-owned URLs only; `null` on competitor entries and on older signals. | `url_movers` is empty for non-citation metrics and for signals detected before movers were recorded. ### Filter signals by mover URL Use `mover_url` to narrow the feed to signals whose citation movers touch a specific page or domain fragment. The match is a case-insensitive substring against each mover's `normalized_url`. ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/signals?metric=cited_domain_rate&mover_url=/pricing&limit=20" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` **Example mover on a returned signal:** ```json theme={null} { "normalized_url": "example.com/pricing", "owner": "brand", "competitor_id": null, "competitor_name": null, "current_responses": 42, "baseline_responses": 71, "current_prompts": 28, "baseline_prompts": 49, "contribution": -0.08 } ``` Signals without any URL movers never match `mover_url`, so combine it with `metric=cited_domain_rate` when you want a citation-focused feed. `%` and `_` in the input are matched literally. *** ## Level signals A `level` signal flags where your brand stands in the current window, with no baseline to compare against. Scrunch evaluates level signals only for brands in their first 60 days of measured data, before a full baseline window exists. A `level` signal fires when your brand sits below one of these references: | Metric | Fixed floor | Behind competitors | | - | - | - | | `presence_rate` | Below 10%, per platform (`account_platform`) | At least 20 percentage points below your competitors' average, per platform or topic | | `cited_domain_rate` | Below 10%, per topic (`topic`) | At least 20 percentage points below your competitors' average, per platform or topic | A slice and metric produce at most one `level` signal. When your brand is under the fixed floor, that signal wins over the competitor comparison. For a level signal, `baseline_value` holds the reference: the 10% floor, or your competitors' average current-window rate. A signal judged against competitors narrates the gap as your rate "against a competitor average of" theirs. Scrunch keeps at most 5 fired `level` signals per brand per night. It ranks them by engine priority score, then by the size of the gap, and keeps the top 5. The rest are stored with the `untested` tier, so the list endpoint leaves them out by default. Pass `tier=untested` to see them. *** ## Signal identity and dedupe Every signal carries a `fingerprint` — a hash over its slice and metric — that stays stable across the nightly re-detection of the same underlying issue. Two implications: * **List responses dedupe to the latest detection.** Over a multi-day `anchor_from`/`anchor_to` window you see one row per fingerprint, not one per day. * **Reactions follow the fingerprint, not the row ID.** A `useful` set today still applies to tomorrow's re-detection of the same signal. Persist the `fingerprint` (not the numeric `id`) if you need to correlate signals across runs in your own system. ### Track one issue over time Use the `fingerprint` filter with a wide `anchor_from` to follow a single issue through remediation. A later detection with the opposite `direction` on the same fingerprint is the recovery (or regression) of the original movement. Fetch the original drop: ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/signals?fingerprint=b1e0c7a4f9e5...&direction=down&anchor_from=2026-04-01&sort=detected_desc" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` Then check whether the same fingerprint has since flipped back up: ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/signals?fingerprint=b1e0c7a4f9e5...&direction=up&anchor_from=2026-04-01&sort=detected_desc" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` Signal detections are retained for 180 days, which covers a 90–120 day remediation tracking window. *** ## Best practices * Poll `/signals/anchors` first to check whether a new detection day exists before pulling the full list. * Sort by `detected_desc` for "what's new" digests, `score_desc` for "what matters most", and `delta_desc` when ranking by raw movement. * Store the `fingerprint` alongside your internal record so reactions and follow-up state survive re-detections. * Use the reactions list to close the loop on "which alerts drove action" — filter by `reaction=actioned` for a running list of resolved signals. * For automated triage from an AI assistant, the same feed is available through the [Scrunch MCP server](/mcp/overview) via the `list_signals` and `get_signal` tools. # Set Signal Reaction Source: https://developers.scrunch.com/api-reference/signals/set-signal-reaction /api-reference/openapi.json put /{brand_id}/signals/{signal_id}/reaction Set (or replace) the calling user's reaction on a signal. Reactions are keyed on the signal's stable `fingerprint`, so a reaction survives the nightly re-detection of the same underlying issue. Requires a **user token** (JWT) — API keys have no user identity to attribute the reaction to and receive 403. # Site Audit API: Score pages for AI search readiness Source: https://developers.scrunch.com/api-reference/site-audit/overview Queue page audits for URLs on your brand's domain and fetch the AI search readiness checks, scores, and previews that power the Site Audit stage. > [!WARNING] > > The Site Audit API is deprecated. Existing integrations keep working, but don't build new ones on it. ## Overview The Site Audit API runs Scrunch's AI search readiness audit against any URL on a brand's domain. Each audit fetches the page, runs the same checks that power the Site Audit stage of the [optimize-and-deploy pipeline](/api-reference/optimize-deploy), and returns a per-check result, an overall score, and a rendered preview of what AI crawlers see. Use it to audit pages on demand from your own automation — for example, after a publish, as part of a CI gate, or to backfill audits for a list of priority URLs. *** ## What the Site Audit API includes * Queue one or many URLs for audit in a single call * Audit status and timestamps (`pending`, `running`, `completed`, `failed`) * Per-check results for the AI search readiness suite (robots, rendering, schema, content quality, and more) * An overall audit score * An AI preview (markdown) showing what AI crawlers extract from the page * A visitor preview image for the rendered page * Filtering and pagination over the brand's audit history Results land in the Scrunch dashboard's Site Audit views and fire the `audit.completed` [webhook](/api-reference/webhooks/overview) on completion. *** ## When to use the Site Audit API Use the Site Audit API when you need to: * Trigger an audit immediately after publishing or updating a page * Re-audit a set of priority URLs on a schedule * Pull audit results into a custom dashboard or report * Programmatically gate a deploy on the audit outcome For audits across the brand's full sitemap, use the [Sitemap API](/api-reference/sitemap/overview) — every page in the sitemap already carries its most recent audit score. *** ## Endpoints | Method | Path | Purpose | | - | - | - | | POST | `/{brand_id}/page-audits` | Queue one or more URLs for audit. | | GET | `/{brand_id}/page-audits` | List audits in reverse chronological order. | | GET | `/{brand_id}/page-audits/{page_audit_id}` | Get a single audit, including check results. | `POST` requires a bearer token with `configure` scope. The `GET` endpoints require `query` scope. See [Authentication](/getting-started/authentication). URLs are normalized and deduplicated before being queued. URLs outside the brand's registered domains are rejected. *** ## Filters The list endpoint supports: | Filter | Description | | - | - | | `status` | Restrict to `pending`, `running`, `completed`, or `failed`. | | `url` | Case-insensitive substring match on the audited URL. | | `limit` | Page size (default `100`). | | `offset` | Offset for pagination. | *** ## Example: queue audits ```bash theme={null} curl -X POST \ "https://api.scrunchai.com/v1/1234/page-audits" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "urls": [ "https://example.com/products/widgets", "https://example.com/blog/launch" ] }' ``` **Response:** ```json theme={null} [ { "url": "https://example.com/products/widgets", "page_audit_id": "01J9Z4K8R0G6M1Q3VN7N0H4T2A" }, { "url": "https://example.com/blog/launch", "page_audit_id": "01J9Z4K8R0G6M1Q3VN7N0H4T2B" } ] ``` Audits start `pending`. Poll the detail endpoint or subscribe to the `audit.completed` webhook to know when results are ready. *** ## Example: fetch an audit result ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/page-audits/01J9Z4K8R0G6M1Q3VN7N0H4T2A" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` A completed response carries the per-check results, an overall score, and previews: ```json theme={null} { "url": "https://example.com/products/widgets", "status": "completed", "result": { "version": 2, "checks": [ { "id": "robots_allows_ai", "passed": true, "score": 1.0 }, { "id": "renders_without_js", "passed": false, "score": 0.0 } ], "visitor_preview_image_url": "https://...", "ai_preview_markdown": "# Widgets\n\nOur flagship..." }, "created_at": "2026-06-05T14:02:00Z", "updated_at": "2026-06-05T14:02:41Z" } ``` While the audit is still in flight, `status` is `pending` or `running` and `result` is `null`. *** ## Example: list recent failed audits ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/page-audits?status=failed&limit=20" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` *** ## Limits and behavior * `POST` accepts up to 100 URLs per call. Submit larger batches across multiple requests. * Submissions are rate-limited at 60 audits per minute per brand. * URLs are normalized (trailing slash, casing) and deduplicated before queueing, so resubmitting the same URL in a batch returns a single ID. * Audits run asynchronously. Typical completion is under a minute; complex pages can take longer. * Audits older than the brand's retention window are pruned from the list endpoint. *** ## Best practices * Prefer the `audit.completed` [webhook](/api-reference/webhooks/overview) over polling — it fires the moment results are available. * Store `page_audit_id` alongside your internal record so you can correlate webhook deliveries back to the URL that triggered them. * Use the `url` filter on the list endpoint to find the latest audit for a specific page without scanning history. * For end-to-end "audit, optimize, deploy" automation, use the [optimize-and-deploy pipeline](/api-reference/optimize-deploy) instead of orchestrating these endpoints by hand. # Apply Page Optimization Source: https://developers.scrunch.com/api-reference/site-optimization/apply-page-optimization /api-reference/openapi.json post /{brand_id}/site-optimization/optimization/apply Record that a page's optimization was **acted on off-platform** — for when the change was made outside Scrunch (e.g. in Sitecore), so no Scrunch review is needed. Send exactly one of: `approve_all: true` to accept every changed block, or a `reviews` list with per-block verdicts by chunk `id` (`approved` keeps our version, `rejected` keeps the original). A `reviews` list can be **partial** — un-verdicted blocks keep the run pending, so blocks can be resolved across several calls. The page is **acknowledged automatically once every changed block has a verdict**, matching the in-app flow that can't close a page with an unresolved block. Applies to the page's latest run. Returns the run (same shape as the optimization endpoint) — `acknowledged` once complete, otherwise still `pending`. Returns 422 when neither or both actions are given, 404 when the page has no run, and 409 for an edge-delivery (AXP-active) page — those go through the edge staging workflow. # Get Page Optimization Detail Source: https://developers.scrunch.com/api-reference/site-optimization/get-page-optimization-detail /api-reference/openapi.json get /{brand_id}/site-optimization/optimization Fetch the latest optimization run for one page: a summary of how many content blocks were transformed / enriched / removed, the optimized token total, and every block's before/after content. By default only **reviewed** runs are returned (`completed`, `staged`, `deployed`, `acknowledged`) — i.e. optimizations a human accepted — not raw unreviewed optimizer output. Pass one or more `status` params to opt into other lifecycle states (e.g. `?status=pending`). Each chunk carries its own `status`, so a `rejected` block (its `after` was not accepted) is distinguishable from an `approved` one. Returns 404 when the page has no run in the requested statuses. # Get Recommendation Type Detail Source: https://developers.scrunch.com/api-reference/site-optimization/get-recommendation-type-detail /api-reference/openapi.json get /{brand_id}/site-optimization/recommendations/by-type/{best_practice_id} One recommendation type's detail: the whole-type header (projected lift and per-state page counts) plus one paginated window of its affected pages, each with its pipeline `state` and the before/after content chunks inline. Use `state` to filter the page window (`all`, `pending`, `reviewed`, `staged`, `deployed`) and `limit`/`offset` to page through it — the header counts always span the whole type. Returns 404 when the brand has no recommendations of this type. # List Page Recommendations Source: https://developers.scrunch.com/api-reference/site-optimization/list-page-recommendations /api-reference/openapi.json get /{brand_id}/site-optimization/recommendations/by-page List the latest recommendations per page for a brand — each page's AI-visibility scores, the recommendations to improve it (in the `opportunities` field), and what it already does well (`strengths`). Pass one or more `path` params (e.g. `?path=/about&path=/pricing`) to scope to specific pages; omit them to page through every audited path. Paths are matched normalized (case-insensitive, trailing slash ignored). Each path returns only its most recent audit. # List Recommendation Types Source: https://developers.scrunch.com/api-reference/site-optimization/list-recommendation-types /api-reference/openapi.json get /{brand_id}/site-optimization/recommendations/by-type List a brand's optimization recommendations grouped by type — one row per best practice, with the projected site-score lift (`site_impact_pp`), how many pages it touches (`page_count`), and where those pages sit in the pipeline (`pending`/`reviewed`/`staged`/`deployed` counts). Counts and lift span the whole brand and match each type's detail view. For a brand using the Site Optimization page selection, they cover its enabled pages instead. Ordered most-affected first. # Site Optimization API: Recommendations, by type and by page Source: https://developers.scrunch.com/api-reference/site-optimization/overview List a brand's optimization recommendations grouped by best practice or per page, with projected site-score lift, plus the optimization run behind any one page. ## Overview The Site Optimization API surfaces the work Scrunch recommends for a brand's pages, and the optimization runs behind them. It answers two questions: * **What should we fix first?** Recommendations grouped **by type** — one row per best practice — with the projected site-score lift for resolving each type. * **What's open on this page?** Recommendations **by page**, with each page's AI-visibility scores, its open recommendations, and what it already does well — plus the block-by-block **optimization run** Scrunch generated for it. *** ## Endpoints | Method | Path | Purpose | | - | - | - | | GET | `/{brand_id}/site-optimization/recommendations/by-type` | Every recommendation type, with projected lift and page counts. | | GET | `/{brand_id}/site-optimization/recommendations/by-type/{best_practice_id}` | One type's detail, plus a paginated window of its affected pages. | | GET | `/{brand_id}/site-optimization/recommendations/by-page` | Latest recommendations per page, optionally scoped to specific paths. | | GET | `/{brand_id}/site-optimization/optimization` | The latest optimization run for one page. | | POST | `/{brand_id}/site-optimization/optimization/apply` | Record that a run was acted on outside Scrunch. | All require a bearer token. The apply endpoint requires the `optimize` scope; the reads require `query`. See [Authentication](/getting-started/authentication). *** ## Example requests Rank the work by type, then open one type: ```bash theme={null} curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \ "https://api.scrunchai.com/v1/1234/site-optimization/recommendations/by-type" ``` ```bash theme={null} curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \ "https://api.scrunchai.com/v1/1234/site-optimization/recommendations/by-type/heading-structure?state=pending&limit=50" ``` Read one page's recommendations, or open its optimization run: ```bash theme={null} curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \ "https://api.scrunchai.com/v1/1234/site-optimization/recommendations/by-page?path=/about&path=/pricing" ``` ```bash theme={null} curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \ "https://api.scrunchai.com/v1/1234/site-optimization/optimization?path=/pricing" ``` *** ## Reading the fields **`site_impact_pp` is percentage points of site score, not a percentage change.** A value of `2.4` means resolving that whole type is projected to move the site score by 2.4 points, not to improve it by 2.4%. **Header counts and the page window are scoped differently.** On the by-type detail endpoint, the per-state counts in the header describe the *entire* type across the brand. The `pages` array beneath them is one paginated window, filtered by `state` and sized by `limit`/`offset`. They will not match, and that is intended — don't compute a total by counting the array. `state` accepts `all`, `pending`, `reviewed`, `staged`, and `deployed`, and filters only the page window. > [!WARNING] > > **`path` is required on the optimization endpoint.** Calling `GET /site-optimization/optimization` without it returns `422`, not an empty result — there is no "all pages" form of that request. The by-page list is the opposite: `path` is optional there, and omitting it pages through every audited path. **Apply records a decision; it does not publish anything.** `POST /optimization/apply` is for changes made *outside* Scrunch — in your CMS, say — so that a run which will never go through Scrunch review is not left looking outstanding. It writes the acknowledgement and returns the run; it does not deploy, and it does not edit your site. Send exactly one of `approve_all: true` or a `reviews` list of per-block verdicts keyed by chunk `id`. **Only reviewed runs come back by default.** The optimization endpoint returns runs a human accepted — `completed`, `staged`, `deployed`, `acknowledged` — and hides raw unreviewed output. Pass `status` explicitly if you need to see a run that nobody has looked at yet. > [!NOTE] > > For a brand using Site Optimization's page selection, by-type counts and lift cover the enabled pages only. Two brands with identical sites can therefore report different totals. > [!NOTE] > > Paths are matched exactly, including the leading slash. `?path=/about` and `?path=about` are not the same request, and the second matches nothing. # Export Sitemap Pages Source: https://developers.scrunch.com/api-reference/sitemap/export-sitemap-pages /api-reference/openapi.json get /{brand_id}/sitemap/export Download every page matching the supplied filters as CSV or XLSX. Uses the same filters as the list endpoint but skips pagination. With `include_metrics=true` (the default), each row also includes totals over the selected date range for `agent_traffic`, `citations`, and `ai_referrals`, plus a percent-change column comparing the first and last buckets of the range — matching the totals and trend percentages shown in the sitemap UI. Limits: - Maximum 10,000 rows per export. - Maximum 366-day window for `start_date`/`end_date`. The response sets `Content-Disposition` with a `sitemap-{brand_id}-{YYYY-MM-DD}.{csv|xlsx}` filename. > [!WARNING] > > The Sitemap API is deprecated. Existing integrations keep working, but don't build new ones on it. # Get Sitemap Page Source: https://developers.scrunch.com/api-reference/sitemap/get-sitemap-page /api-reference/openapi.json get /{brand_id}/sitemap/pages/{page_id} Get detailed information about a single page in the brand's sitemap, including title, description, depth, audit score, canonical URL, last-indexed timestamp, priority flag, and optimized-content flag. > [!WARNING] > > The Sitemap API is deprecated. Existing integrations keep working, but don't build new ones on it. # Get Sitemap Page Metrics Source: https://developers.scrunch.com/api-reference/sitemap/get-sitemap-page-metrics /api-reference/openapi.json get /{brand_id}/sitemap/pages/{page_id}/metrics Return time-series performance metrics for a single page: citations, AI referrals, and AI agent traffic. Each metric is reported as a list of buckets keyed by date, with counts broken down by AI platform. Granularity is chosen automatically based on the requested date range — short ranges return daily buckets, longer ranges return weekly buckets. Date ranges are capped at 366 days. > [!WARNING] > > The Sitemap API is deprecated. Existing integrations keep working, but don't build new ones on it. # List Sitemap Pages Source: https://developers.scrunch.com/api-reference/sitemap/list-sitemap-pages /api-reference/openapi.json get /{brand_id}/sitemap/pages List pages discovered in the brand's sitemap with their title, description, depth, audit score, priority flag, and optimized-content flag. Results come from the most recent completed crawl for the brand. Supports filtering by domain, URL depth, path prefix, priority flag, optimized-content flag, and a case-insensitive substring search across the page URL and title. Results are paginated and ordered by depth then URL. > [!WARNING] > > The Sitemap API is deprecated. Existing integrations keep working, but don't build new ones on it. # Sitemap API: Pages, Audit Scores, AI Metrics Source: https://developers.scrunch.com/api-reference/sitemap/overview List, inspect, and export pages from your brand's sitemap with audit scores, citations, AI referrals, and bot traffic metrics for each URL. > [!WARNING] > > The Sitemap API is deprecated. Existing integrations keep working, but don't build new ones on it. ## Overview The Sitemap API exposes the pages Scrunch has discovered while crawling your brand's sites, together with their AI search readiness audit score, priority and optimized-content flags, and per-page time-series metrics for citations, AI referrals, and AI agent traffic. Use it to enumerate the pages in your sitemap, drill into a single page, pull its performance trend, or dump everything to CSV or XLSX for downstream reporting. All endpoints are read-only and return data from the most recent completed (non-stale) crawl for the brand. *** ## What the Sitemap API includes * The pages from the brand's latest finished crawl, paginated and filterable * Title, meta description, depth, canonical URL, and most recent audit score * Priority flag (matches the brand's `priority_page` and `priority_path` overrides) * Optimized-content flag (page has active AXP content deployed) * Per-page time-series for citations, AI referrals, and AI agent traffic, bucketed daily or weekly * A full CSV or XLSX export that mirrors the filters, columns, and trend percentages from the sitemap view in the Scrunch dashboard *** ## When to use the Sitemap API Use the Sitemap API when you need to: * Build a content inventory for the brand from the latest crawl * Identify priority pages or pages missing optimized content * Pull per-page citations, AI referrals, or agent traffic for a custom dashboard * Export the sitemap (with totals and trends) to a spreadsheet for review For aggregated bot traffic across a whole site, use the [Agent Traffic API](/api-reference/agent-traffic/overview) instead. *** ## Endpoints | Method | Path | Purpose | | - | - | - | | GET | `/{brand_id}/sitemap/pages` | Paginated list of pages with filters. | | GET | `/{brand_id}/sitemap/pages/{page_id}` | Detail for a single page. | | GET | `/{brand_id}/sitemap/pages/{page_id}/metrics` | Time-series metrics for one page. | | GET | `/{brand_id}/sitemap/export` | CSV or XLSX export of the filtered page set. | All endpoints require a bearer token with `query` scope. See [Authentication](/getting-started/authentication). *** ## Filters The list and export endpoints share the same filter set: | Filter | Description | | - | - | | `domain` | Restrict to a specific domain when the brand has multiple registered sites. | | `max_depth` | Maximum URL path depth (`0` = root only). | | `path_prefix` | Segment-aligned path prefix. `/blog` matches `/blog` and `/blog/post` but not `/blogger`. | | `is_priority` | Keep only (or exclude) pages flagged as priority for the brand. | | `has_optimized_content` | Keep only (or exclude) pages with active AXP optimized content. | | `search` | Case-insensitive substring match on the page URL or title. | The list endpoint additionally supports `limit` and `offset` for pagination. *** ## Example: list pages ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/sitemap/pages?max_depth=2&is_priority=true&limit=20" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` **Response:** ```json theme={null} { "items": [ { "id": 9087, "url": "https://example.com/products/widgets", "title": "Widgets — Example", "description": "Our flagship widget lineup.", "depth": 2, "audit_score": 84, "canonical_url": "https://example.com/products/widgets", "is_priority": true, "has_optimized_content": false } ], "total": 1, "offset": 0, "limit": 20, "domain": "example.com", "last_crawl_completed": "2025-05-08T03:14:00Z" } ``` *** ## Example: per-page metrics ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/sitemap/pages/9087/metrics?start_date=2025-04-01&end_date=2025-05-01" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" ``` The response returns three series (`citations`, `ai_referrals`, `agent_traffic`), each as a list of buckets keyed by ISO date with counts split by AI platform. Granularity (`daily` or `weekly`) is chosen automatically based on the requested range. *** ## Example: export to XLSX ```bash theme={null} curl -X GET \ "https://api.scrunchai.com/v1/1234/sitemap/export?format=xlsx&include_metrics=true&start_date=2025-04-01&end_date=2025-05-01" \ -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ -o sitemap.xlsx ``` With `include_metrics=true` (the default), each row carries totals for `agent_traffic`, `citations`, and `ai_referrals` over the supplied date range, plus a percent-change column comparing the first and last buckets — matching the trend percentages shown in the dashboard. The filename comes from the response's `Content-Disposition` header. *** ## Limits and behavior * The export endpoint caps at **10,000 rows** per call. Tighten the filters or contact support for a bulk export. * The metrics and export endpoints cap the `start_date`/`end_date` window at **366 days**. * All endpoints read from the most recent completed, non-stale crawl. If no crawl has finished, the list endpoint returns `404`. * User-controlled strings (URL, title, description, canonical URL) are sanitized in CSV and XLSX output to prevent spreadsheet formula injection. *** ## Best practices * Use `path_prefix` to scope queries to a section of the site rather than filtering client-side. * Use `search` for find-as-you-type style flows; it matches the dashboard's "Find pages…" input. * Pull metrics in **weekly** granularity (longer ranges) for trend reporting; the API chooses this automatically when the range exceeds the daily cap. * Pair `is_priority=true` with the export endpoint to produce a focused priority-page report. # Update Brand Source: https://developers.scrunch.com/api-reference/update-brand /api-reference/openapi.json patch /brands/{brand_id} Partially update a brand. Only fields included in the request body are modified. For competitors and personas, the provided list represents the full desired state: include an `id` to update an existing record, omit `id` to create a new one, and any existing records not in the list are archived. When a persona is archived this way, its active prompts are paused: collection stops but their collected history stays available on the API. If you submit a persona without an `id` and its `name` matches a previously archived persona on the same brand, the archived persona is reactivated (its `status` returns to `active` and its `description` is updated) instead of creating a duplicate. This avoids unique-name conflicts when reusing a name that was previously archived. # Update Competitor Source: https://developers.scrunch.com/api-reference/update-competitor /api-reference/openapi.json put /brands/{brand_id}/competitors/{competitor_id} Update a competitor # Update Persona Source: https://developers.scrunch.com/api-reference/update-persona /api-reference/openapi.json put /brands/{brand_id}/personas/{persona_id} Update a persona # Update Prompt Status Source: https://developers.scrunch.com/api-reference/update-prompt-status /api-reference/openapi.json patch /{brand_id}/prompts/{prompt_id} Pauses or resumes a prompt. Requires the `configure` scope. **Pausing** (`status: paused`) stops collection for the prompt and releases its variants from the organization's prompt pool. The prompt keeps its configuration and all of its collected history, and stays readable through `GET /{brand_id}/prompts?status=paused`. **Resuming** (`status: active`) restores the exact deployment the prompt had when it was paused and re-checks the prompt pool, so it can return `429 quota_exceeded` when the organization no longer has room for the prompt's variants. Both transitions are idempotent: a prompt already in the requested status returns `200` with the prompt, unchanged. A transition the prompt's status does not allow (resuming an archived prompt, resuming one whose persona is archived) returns `409` with a `type` naming the reason. To archive a prompt, use `DELETE /{brand_id}/prompts/{prompt_id}` instead. # Webhooks: Pipeline Stage Completion Callbacks Source: https://developers.scrunch.com/api-reference/webhooks/overview Subscribe to real-time webhook callbacks for Optimize and Deploy pipeline events including audit, optimization, and AXP deployment completion. > [!NOTE] > > Webhook documentation is coming soon. Contact your Customer Success representative for early access setup instructions. Webhooks let you receive HTTP callbacks at each stage of the Optimize and Deploy pipeline — eliminating the need to poll for status. ## Events | Event | Fired when | | - | - | | `audit.completed` | A page audit finishes | | `optimization.completed` | Content optimization finishes. Payload includes `status: "staged"` when optimized content was staged to AXP via `stage_axp: true`. | | `deployment.completed` | An AXP deployment finishes | | `pipeline.completed` | All URLs in a batch have finished | ## Coming soon Full documentation including payload schemas, signature verification, and retry behavior will be published here when webhooks reach general availability. # Provision an API key Source: https://developers.scrunch.com/getting-started/authentication Create, scope, and rotate Scrunch API keys at the organization level to authenticate Query, Responses, Configuration, and Agent Traffic requests. Scrunch API keys authenticate your requests and define which brands and operations your integration can access. Only organization admins can create or manage API keys. > [!NOTE] > > API keys are shown **once** at creation time. Be sure to copy and store them securely. ## Plan Requirements API key creation is available on the **Agency** and **Enterprise** plans. If your organization is on a different plan, the **New API Key** button is disabled and you'll see an upgrade prompt when attempting to create one. If you need API access on another plan, contact [support@scrunchai.com](mailto:support@scrunchai.com) to discuss an override for your organization. > [!NOTE] > > Attempts to call `POST /organizations/{organization_id}/api-keys` without the required plan capability return HTTP `402 Payment Required`. ## Where API Keys Live API keys are managed at the organization level. You can find them by clicking your **organization name** in the top-left corner of the Scrunch dashboard, then selecting **API Keys**. This area is available only to organization admins and is also where you manage brands and archival operations. ## Create an API Key Complete these steps in your Scrunch UI to provision an API Key (`$SCRUNCH_API_TOKEN`). **1. Open the organization menu** Click your **organization name** in the top-left corner of the Scrunch dashboard. ![Organization selector showing API access](https://mintcdn.com/scrunchai/jjpfPER2d5Ppa7xu/images/org_settings.png?fit=max\&auto=format\&n=jjpfPER2d5Ppa7xu\&q=85\&s=2bd8a5534c8347244122b1b564b7a994) **2. Open API Keys** Select **API Keys** from the organization menu. ![Screenshot 2026 03 05 At 2 07 51 PM](https://mintcdn.com/scrunchai/-UAm6mPL0fGNQQb9/images/Screenshot2026-03-05at2.07.51PM.png?fit=max\&auto=format\&n=-UAm6mPL0fGNQQb9\&q=85\&s=94a16d4455ea35058bf4358faaa81ddd) **3. Create a new API key** Click **+ New API Key**. **4. Choose the key scope** Scrunch supports several operational scopes: * Query (retrieve analytics and metrics) * Configure (update brand configuration, prompts, etc.) * Create Brand (programmatically create brands) * Optimize (manage Agent Pages and Site Optimization) Choose the minimal scope required for your integration. ![Screenshot 2026 03 05 At 2 08 43 PM](https://mintcdn.com/scrunchai/-UAm6mPL0fGNQQb9/images/Screenshot2026-03-05at2.08.43PM.png?fit=max\&auto=format\&n=-UAm6mPL0fGNQQb9\&q=85\&s=c805071a7f38ebadbd28b4310dfe6d7b) **5. Select brand access** You may scope the key to: * **Specific brand(s)** (recommended for client-facing reporting) * **All brands** (recommended for internal tooling or ETL pipelines) **6. Create and copy the key** Scrunch displays the key **once**. Copy it immediately and store it securely. ## Use Your API Key Include your key as a Bearer token in the `Authorization` header. ```bash theme={null} export SCRUNCH_API_TOKEN="your-key" curl -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \ https://api.scrunchai.com/v1/brands ``` ## Best Practices > [card] Use brand-scoped keys > > Limit access when integrating with client-facing dashboards or BI tools. > [card] Reserve org-wide keys > > Use for internal workflows only (e.g., multi-brand ETL, automation). > [card] Rotate keys periodically > > Especially important for deployments or CI environments. > [card] Archive inactive clients > > Keeps your organization clean and prevents accidental access. ## Troubleshooting > [!WARNING] > > If you don't see the **API Keys** tab, you are likely not an organization admin. Contact your Scrunch admin or [support@scrunchai.com](mailto:support@scrunchai.com). If a key cannot access a brand: * Verify the key's scope includes that brand * Check that the brand has not been archived # Optimize and Deploy Quickstart Source: https://developers.scrunch.com/getting-started/quickstart-orchestration Step-by-step guide to submitting pages for AI search audit, content optimization, and AXP deployment using a single Scrunch pipeline API call. > [!WARNING] > > The Optimize and Deploy API is currently in **early access**. Contact your Customer Success representative to get access enabled for your organization. ### Prerequisites * A Scrunch workspace with **Optimize and Deploy** access enabled * An API key with **Configure** access * A **brand ID** for the brand you want to optimize * (Optional) A **site ID** if you want to deploy to AXP *** ### Run your first pipeline > [tab] cURL > > **1. Set your credentials** > > ```bash theme={null} > export SCRUNCH_API_KEY="your-api-key-here" > export SCRUNCH_BRAND_ID="your-brand-id" > ``` > > **2. Submit URLs for audit and optimization** > > This example submits two URLs for audit and content optimization: > > ```bash theme={null} > curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/$SCRUNCH_BRAND_ID" \ > -H "Authorization: Bearer $SCRUNCH_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "urls": [ > "https://example.com/page-a", > "https://example.com/page-b" > ], > "optimize": true > }' > ``` > > **Example response:** > > ```json theme={null} > { > "pipeline_id": null, > "tokens": [ > { > "token": "01JABC00000000000000001", > "url": "https://example.com/page-a", > "status": "pending", > "orchestration_status": "audit" > }, > { > "token": "01JABC00000000000000002", > "url": "https://example.com/page-b", > "status": "pending", > "orchestration_status": "audit" > } > ], > "status": "pending" > } > ``` > > **3. Poll for status** > > Use a token from the response to check progress: > > ```bash theme={null} > curl "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/$SCRUNCH_BRAND_ID/01JABC00000000000000001" \ > -H "Authorization: Bearer $SCRUNCH_API_KEY" > ``` > > **Example response (completed):** > > ```json theme={null} > { > "token": "01JABC00000000000000001", > "url": "https://example.com/page-a", > "status": "completed", > "orchestration_status": "completed", > "optimization_run_id": "01JOPTRUN0000000000000", > "axp_version_id": null, > "result": { > "checks": [], > "access_controls_score": 100, > "content_delivery_score": 90, > "content_quality_score": 85 > }, > "created_at": "2025-02-06T10:00:00Z", > "updated_at": "2025-02-06T10:02:30Z" > } > ``` > [tab] Python > > **1. Install dependencies** > > ```bash theme={null} > pip install requests > ``` > > **2. Submit and poll** > > ```python theme={null} > import requests > import time > > API_KEY = "your-api-key" > BRAND_ID = "your-brand-id" > BASE = f"https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/{BRAND_ID}" > HEADERS = {"Authorization": f"Bearer {API_KEY}"} > > # Submit URLs > resp = requests.post(BASE, headers=HEADERS, json={ > "urls": [ > "https://example.com/page-a", > "https://example.com/page-b", > ], > "optimize": True, > }, timeout=30) > resp.raise_for_status() > pipeline = resp.json() > > # Poll each token until done > for record in pipeline["tokens"]: > token = record["token"] > while True: > status = requests.get( > f"{BASE}/{token}", headers=HEADERS, timeout=30 > ).json() > stage = status["orchestration_status"] > print(f"{token}: {stage}") > if stage in ("completed", "failed"): > break > time.sleep(5) > ``` > > **3. Run your script** > > ```bash theme={null} > python orchestration.py > ``` > [tab] JavaScript / TypeScript > > **1. Install Axios** > > ```bash theme={null} > npm install axios > ``` > > **2. Submit and poll** > > ```javascript theme={null} > import axios from "axios"; > > const API_KEY = "your-api-key"; > const BRAND_ID = "your-brand-id"; > const BASE = `https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/${BRAND_ID}`; > const headers = { Authorization: `Bearer ${API_KEY}` }; > > async function main() { > // Submit URLs > const { data: pipeline } = await axios.post(BASE, { > urls: [ > "https://example.com/page-a", > "https://example.com/page-b", > ], > optimize: true, > }, { headers }); > > // Poll each token > for (const record of pipeline.tokens) { > let stage = record.orchestration_status; > while (stage !== "completed" && stage !== "failed") { > await new Promise((r) => setTimeout(r, 5000)); > const { data: status } = await axios.get( > `${BASE}/${record.token}`, { headers } > ); > stage = status.orchestration_status; > console.log(`${record.token}: ${stage}`); > } > } > } > > main().catch(console.error); > ``` > > **3. Run your code** > > ```bash theme={null} > node orchestration.js > ``` *** ## Next steps > [card] [Orchestration overview](/api-reference/optimize-deploy) > > Learn about pipeline stages, error codes, and request patterns. > [card] [Pipeline lifecycle guide](/guides/orchestration-lifecycle) > > Walk through the full lifecycle from submission to completion. > [card] [Set up webhooks](/api-reference/webhooks/overview) > > Get notified in real time instead of polling. # Query API Quickstart Source: https://developers.scrunch.com/getting-started/quickstart-query Step-by-step walkthrough for your first Scrunch Query API call to fetch weekly brand presence, sentiment, and AI visibility metrics by platform. ### Prerequisites * A Scrunch workspace * An API key with **Query** access * A **brand ID** for the brand you want to query *** ### Call the API > [tab] cURL > > **1. Set your API key** > > Get your API key from **Organization Settings → API Keys** and set it and your brand ID as environment variables: > > ```bash theme={null} > export SCRUNCH_API_KEY="your-api-key-here" > export SCRUNCH_BRAND_ID="your-brand-id" > ``` > > **2. Make your first Query API request** > > This example retrieves **weekly brand presence** for the last 30 days. > > ```bash theme={null} > curl "https://api.scrunchai.com/v1/$SCRUNCH_BRAND_ID/query?fields=date_week,brand_presence_percentage&start_date=2025-01-01&end_date=2025-01-31" \ > -H "Authorization: Bearer $SCRUNCH_API_KEY" \ > -H "Accept: application/json" > ``` > > **Example output:** > > ```json theme={null} > { > "total": 4, > "limit": 1000, > "offset": 0, > "rows": [ > { > "date_week": "2025-01-06", > "brand_presence_percentage": 42.1 > }, > { > "date_week": "2025-01-13", > "brand_presence_percentage": 47.8 > } > ] > } > ``` > [tab] Python > > **1. Install dependencies** > > ```bash theme={null} > pip install requests pandas > ``` > > **2. Create your script** > > ```python theme={null} > import requests > import pandas as pd > > API_KEY = "your-api-key" > BRAND_ID = "your-brand-id" > BASE_URL = f"https://api.scrunchai.com/v1/{BRAND_ID}/query" > > params = { > "fields": "date_week,brand_presence_percentage", > "start_date": "2025-01-01", > "end_date": "2025-01-31", > } > > response = requests.get( > BASE_URL, > headers={"Authorization": f"Bearer {API_KEY}"}, > params=params, > timeout=30, > ) > response.raise_for_status() > > data = response.json() > df = pd.DataFrame(data) > print(df) > ``` > > **3. Run your code** > > ```bash theme={null} > python quickstart.py > ``` > [tab] JavaScript / TypeScript > > **1. Install Axios** > > ```bash theme={null} > npm install axios > ``` > > **2. Create your code** > > ```javascript theme={null} > import axios from "axios"; > > const API_KEY = "your-api-key"; > const BRAND_ID = "your-brand-id"; > > async function main() { > const url = `https://api.scrunchai.com/v1/${BRAND_ID}/query`; > > const response = await axios.get(url, { > headers: { Authorization: `Bearer ${API_KEY}` }, > params: { > fields: "date_week,brand_presence_percentage", > start_date: "2025-01-01", > end_date: "2025-01-31", > }, > }); > > console.log(response.data.rows); > } > > main().catch(console.error); > ``` > > **3. Run your code** > > ```bash theme={null} > node quickstart.js > ``` *** ## Next steps > [card] [Query API overview](/api-reference/query/overview) > > Learn how fields, dimensions, and metrics work together. > [card] [Build dashboards](/integrations/looker-studio) > > Send Query data into Looker Studio or your BI tool. > [card] [Responses API](/api-reference/responses/overview) > > Get full answers, citations, and sentiment when you need row-level detail. # Responses API Quickstart Source: https://developers.scrunch.com/getting-started/quickstart-responses Use the Responses API to retrieve full AI answers, citations, sentiment, competitors, and metadata for every Scrunch prompt execution. ### Prerequisites * A Scrunch workspace * An API key with **Responses** access * A **brand ID** for the brand you want to fetch responses for > The Responses API returns **row-level data**. It is ideal for warehouses, BI tools, audits, DE workflows, and custom analysis. > [!NOTE] > > You may need to reach out to your Scrunch rep for Responses API access. *** ### Call the API > [tab] cURL > > **1. Set your API key** > > ```bash theme={null} > export SCRUNCH_API_KEY="your-api-key-here" > export SCRUNCH_BRAND_ID="your-brand-id" > ``` > > **2. Call the Responses API** > > This example retrieves responses for a single day (Scrunch recommends syncing by date windows). > > ```bash theme={null} > curl "https://api.scrunchai.com/v1/$SCRUNCH_BRAND_ID/responses?start_date=2025-01-01&end_date=2025-01-02&limit=100" \ > -H "Authorization: Bearer $SCRUNCH_API_KEY" \ > -H "Accept: application/json" > ``` > > **Example output:** > > ```json theme={null} > { > "total": 128, > "limit": 100, > "offset": 0, > "items": [ > { > "id": "resp_01jk93mc9p", > "created_at": "2025-01-01T05:12:41.000Z", > "prompt_id": "pr_01hd8j39s", > "prompt": "Which mattress brands are recommended for side sleepers?", > "platform": "chatgpt", > "brand_present": true, > "brand_sentiment": "positive", > "brand_position": 1, > "response_text": "For side sleepers, the best mattresses tend to...", > "citations": [ > { > "url": "https://www.example.com/review", > "title": "2024 mattress comparison", > "source_type": "other" > } > ], > "competitors": [ > { "name": "Casper", "present": true, "sentiment": "neutral" }, > { "name": "Purple", "present": true, "sentiment": "positive" } > ], > "tags": ["mattress", "comparison"], > "stage": "evaluation" > } > ] > } > ``` > > **3. Paginate through responses** > > Use the `offset` parameter to retrieve subsequent batches: > > ```bash theme={null} > curl "https://api.scrunchai.com/v1/$SCRUNCH_BRAND_ID/responses?start_date=2025-01-01&end_date=2025-01-02&limit=100&offset=100" \ > -H "Authorization: Bearer $SCRUNCH_API_KEY" > ``` > [tab] Python > > **1. Install dependencies** > > ```bash theme={null} > pip install requests pandas > ``` > > **2. Create your script** > > ```python theme={null} > import requests > import pandas as pd > > API_KEY = "your-api-key" > BRAND_ID = "your-brand-id" > BASE_URL = f"https://api.scrunchai.com/v1/{BRAND_ID}/responses" > > params = { > "start_date": "2025-01-01", > "end_date": "2025-01-02", > "limit": 100, > "offset": 0 > } > > all_rows = [] > > while True: > response = requests.get( > BASE_URL, > headers={"Authorization": f"Bearer {API_KEY}"}, > params=params, > timeout=60 > ) > response.raise_for_status() > > data = response.json() > items = data["items"] > all_rows.extend(items) > > if params["offset"] + params["limit"] >= data["total"]: > break > > params["offset"] += params["limit"] > > df = pd.DataFrame(all_rows) > print(df.head()) > ``` > > **3. Run your script** > > ```bash theme={null} > python responses_quickstart.py > ``` > [tab] JavaScript / TypeScript > > **1. Install Axios** > > ```bash theme={null} > npm install axios > ``` > > **2. Create your script** > > ```javascript theme={null} > import axios from "axios"; > > const API_KEY = "your-api-key"; > const BRAND_ID = "your-brand-id"; > > async function fetchResponses() { > let offset = 0; > const limit = 100; > const all = []; > > while (true) { > const res = await axios.get( > `https://api.scrunchai.com/v1/${BRAND_ID}/responses`, > { > headers: { Authorization: `Bearer ${API_KEY}` }, > params: { > start_date: "2025-01-01", > end_date: "2025-01-02", > limit, > offset, > }, > } > ); > > all.push(...res.data.items); > > if (offset + limit >= res.data.total) break; > offset += limit; > } > > console.log(all.slice(0, 3)); > } > > fetchResponses().catch(console.error); > ``` > > **3. Run your script** > > ```bash theme={null} > node responses.js > ``` *** ## When to use the Responses API Use the Responses API when you need: * Full AI-generated answers * Citations and source URLs used in responses * Per-response presence, position, sentiment * Competitor mentions * Metadata (stage, tags, topics, platform, persona) * Warehouse or BI-level granularity *** ## Next steps > [card] [Responses API overview](/api-reference/responses/overview) > > Explore the response schema and filtering options. > [card] \[Coming soon] ETL best practices > > Learn how to sync Responses into BigQuery, Snowflake, or Redshift. > [card] [Query API](/api-reference/query/overview) > > Use Query for trends, aggregates, comparisons, and dashboards. # Send Agent Traffic via API Source: https://developers.scrunch.com/guides/agent-traffic-api-integration Forward AI bot traffic logs to Scrunch from any CDN, edge worker, or hosting environment using the custom Agent Traffic ingestion endpoint and JSON or NDJSON. ## Overview The Agent Traffic API lets you send web traffic logs to Scrunch from any platform or hosting environment — including CDNs and setups that don't have a native Scrunch integration. Once data is flowing, Scrunch automatically classifies each request by bot type (retrieval, training, indexer) and agent source (GPTBot, ClaudeBot, and others). Once connected, the Agent Traffic dashboard will show: * Total bot traffic for the selected period and a comparison to the prior period * Bot traffic over time and distribution across Retrieval, Indexer, and Training types * Top bot agents and when they were last seen * Top content pages accessed by LLM bots * Recent bot requests * A date filter for the last 24 hours, 7 days, or 30 days This guide covers: * Setting up a site with the API platform in the dashboard * Sending single events and batches * Backfilling historical log data * Managing multiple sites (for agencies and multi-brand setups) * Retry logic and error handling *** ## Prerequisites * A Scrunch account with Agent Traffic access * Access to your web server or CDN access logs * Your site's domain (e.g., `example.com`) *** ## Step 1: Create a site with the API platform 1. In the Scrunch dashboard, open the **Agent Traffic** page. 2. Click **+ Connect Site**. 3. Enter your domain and select **API** as the platform. 4. A dedicated instructions page will appear showing your **Site ID**, **Webhook URL**, and **API Key**. Copy all three — you will need them for every request. > [!NOTE] > > Each site has its own endpoint and key. Don't reuse them across different sites or integrations. > [!NOTE] > > Your site will show a **pending** status until the first valid request is received. It transitions to **active** automatically within 5–10 minutes. ![Screenshot 2026 04 27 At 1 25 17 PM](https://mintcdn.com/scrunchai/Nuw3yM57EA0775TW/images/Screenshot-2026-04-27-at-1.25.17-PM.png?fit=max\&auto=format\&n=Nuw3yM57EA0775TW\&q=85\&s=e4e19f2a151605b7747df1e0f249def4) *** ## Step 2: Send your first event ### Endpoint ```text theme={null} POST https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic ``` ### Authentication Include the API key in the `X-Api-Key` header: ```text theme={null} X-Api-Key: ``` ![Screenshot 2026 04 27 At 1 26 12 PM](https://mintcdn.com/scrunchai/Nuw3yM57EA0775TW/images/Screenshot-2026-04-27-at-1.26.12-PM.png?fit=max\&auto=format\&n=Nuw3yM57EA0775TW\&q=85\&s=96c96013ad2c7b6a730bca5f46e5d8d2) ### Required fields | Field | Type | Description | | - | - | - | | `domain` | string | The domain of the site (e.g. `example.com`) | | `user_agent` | string | The full, original User-Agent string from the request | | `url` | string | Full URL (e.g. `https://example.com/blog/post`) | | `path` | string | URL path only (e.g. `/blog/post`) | | `method` | string | HTTP method (e.g. `GET`) | | `status_code` | integer | HTTP response status code (e.g. `200`) | | `timestamp` | integer \| float | Unix epoch in seconds (e.g. `1700000000`) | ### Optional fields | Field | Type | Description | | - | - | - | | `response_time` | integer | Response time in milliseconds | | `ip` | string | IP address of the requesting client | > [!WARNING] > > Always pass the **original, unmodified** `user_agent` string from the incoming request. Scrunch's bot classification runs entirely off this field. Truncating or transforming it will result in incorrect or missing bot detection. ### Single event (cURL) Use `Content-Type: application/json` and send one JSON object per request: ```bash theme={null} curl -X POST "https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic" \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_API_KEY" \ -d '{ "domain": "example.com", "user_agent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)", "url": "https://example.com/blog/post", "path": "/blog/post", "method": "GET", "status_code": 200, "timestamp": 1700000000, "response_time": 120, "ip": "203.0.113.1" }' ``` A successful response returns: ```json theme={null} { "status": "ok" } ``` *** ## Step 3: Send batches with NDJSON For production use, send multiple events per request using newline-delimited JSON (NDJSON). Each line is a complete JSON object. This reduces request overhead and is the recommended approach for any significant traffic volume. Use `Content-Type: application/x-ndjson`: ```bash theme={null} curl -X POST "https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic" \ -H "Content-Type: application/x-ndjson" \ -H "X-Api-Key: YOUR_API_KEY" \ -d '{"domain":"example.com","user_agent":"Mozilla/5.0 (compatible; GPTBot/1.0)","url":"https://example.com/page-1","path":"/page-1","method":"GET","status_code":200,"timestamp":1700000000} {"domain":"example.com","user_agent":"Mozilla/5.0 (compatible; ClaudeBot/1.0)","url":"https://example.com/page-2","path":"/page-2","method":"GET","status_code":200,"timestamp":1700000060,"response_time":95}' ``` Keep each batch **under 1 MB uncompressed**. Split larger payloads into multiple requests. *** ## Step 4: Verify your integration After sending your first request, wait up to 5–10 minutes for your site to show as **Active** in Scrunch. If you don't see traffic appearing, send a test event using a known bot User-Agent to confirm your credentials and pipeline are working: ```bash theme={null} curl -X POST "https://webhooks.scrunchai.com/v1/sites/{site_id}/platforms/custom/web-traffic" \ -H "Content-Type: application/json" \ -H "X-Api-Key: YOUR_API_KEY" \ -d '{ "domain": "yourdomain.com", "user_agent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)", "url": "https://yourdomain.com/test-page", "path": "/test-page", "method": "GET", "status_code": 200, "timestamp": 1700000000 }' ``` If this returns `{ "status": "ok" }` but traffic still doesn't appear after 10 minutes, check the troubleshooting section below. *** ## Step 5: Backfill historical data with Python If you have existing access logs, use this script to send them in batches. It reads a CSV of log entries, maps fields to the API schema, and sends NDJSON batches with retry handling for rate limits. ### Expected CSV format Your CSV should have columns matching the required and optional fields. At minimum: ```text theme={null} timestamp,domain,user_agent,url,path,method,status_code,response_time_ms,ip_address 1700000000,example.com,"Mozilla/5.0 (compatible; GPTBot/1.0)",https://example.com/page,/page,GET,200,120,203.0.113.1 ``` ### Backfill script ```python theme={null} import csv import json import time import requests API_KEY = "your-jwt-token" SITE_ID = "your-site-id" ENDPOINT = f"https://webhooks.scrunchai.com/v1/sites/{SITE_ID}/platforms/custom/web-traffic" BATCH_SIZE_BYTES = 1_000_000 # 1 MB per batch def load_payloads(csv_path: str) -> list[dict]: """Read a CSV of access log rows and map to API payload format.""" payloads = [] with open(csv_path, encoding="utf-8") as f: reader = csv.DictReader(f) for row in reader: domain = row.get("domain", "") path = row.get("path", "/") or "/" payload = { "domain": domain, "user_agent": row.get("user_agent", ""), "url": row.get("url", "") or f"https://{domain}{path}", "path": path, "method": row.get("method", "GET") or "GET", "status_code": int(row.get("status_code", "200") or "200"), "timestamp": int(row.get("timestamp", "0") or "0"), "response_time": int(row.get("response_time_ms", "0") or "0"), "ip": row.get("ip_address") or None, } payloads.append(payload) return payloads def build_batches(payloads: list[dict], max_bytes: int = BATCH_SIZE_BYTES) -> list[list[dict]]: """Split payloads into batches that fit within max_bytes uncompressed.""" batches, current, current_size = [], [], 0 for p in payloads: size = len(json.dumps(p).encode()) + 1 # +1 for newline if current and current_size + size > max_bytes: batches.append(current) current, current_size = [], 0 current.append(p) current_size += size if current: batches.append(current) return batches def send_batch(batch: list[dict], retries: int = 3) -> None: """Send a single NDJSON batch with retry logic for rate limits.""" ndjson = "\n".join(json.dumps(p) for p in batch) + "\n" for attempt in range(retries): response = requests.post( ENDPOINT, content=ndjson.encode("utf-8"), headers={ "Content-Type": "application/x-ndjson", "X-Api-Key": API_KEY, }, timeout=60, ) if response.status_code == 200: return if response.status_code == 429: wait = int(response.headers.get("Retry-After", 5)) print(f"Rate limited. Retrying in {wait}s...") time.sleep(wait) else: response.raise_for_status() raise RuntimeError(f"Failed to send batch after {retries} attempts") def main(csv_path: str) -> None: payloads = load_payloads(csv_path) batches = build_batches(payloads) print(f"Loaded {len(payloads)} events across {len(batches)} batch(es)") for i, batch in enumerate(batches, 1): print(f"Sending batch {i}/{len(batches)} ({len(batch)} events)...") send_batch(batch) print(f" Batch {i} sent successfully") print("Done.") if __name__ == "__main__": import sys main(sys.argv[1]) ``` Run it: ```bash theme={null} python backfill.py your_logs.csv ``` *** ## Managing multiple sites If you are an agency or managing multiple brands, each domain requires its own site entry in the dashboard with its own Site ID and API key. Never reuse credentials across sites — each site's key is scoped to that domain only. The sending logic is identical across all sites — only the `site_id` in the URL and the `X-Api-Key` header change per site. A common pattern for multi-site setups: ```python theme={null} SITES = [ {"site_id": "01ABC...", "api_key": "token-for-site-a", "domain": "brand-a.com"}, {"site_id": "01DEF...", "api_key": "token-for-site-b", "domain": "brand-b.com"}, ] for site in SITES: # filter payloads for this domain, then send site_payloads = [p for p in all_payloads if p["domain"] == site["domain"]] # ... send using site["site_id"] and site["api_key"] ``` This approach scales well when onboarding many brands: provision each site in the dashboard, collect credentials, and run the same pipeline with different configuration per site. *** ## Tips for better results * **Use NDJSON batching** to reduce request overhead for high-traffic sites. * **Keep batch sizes under 1 MB** uncompressed for optimal performance. * **Always pass the original, unmodified User-Agent string** — Scrunch uses it to classify the bot. Never transform or truncate it. * **Exclude static asset paths** (CSS, JS, images) if you want cleaner data focused on content pages. * **Include paths that serve PDFs** — AI bots frequently request them. * **Never reuse credentials across sites** — provision a separate Site ID and API key for each domain. *** ## Error handling | Status | Meaning | Action | | - | - | - | | `200` | Accepted and queued | No action needed | | `401` | Invalid or missing API key | Verify the `X-Api-Key` value and header name | | `422` | Validation error | Check all required fields are present and correctly typed | | `429` | Rate limited | Wait and retry; respect the `Retry-After` response header | | `500` | Server error | Retry with exponential backoff; contact support if persistent | *** ## Troubleshooting **Site is stuck in pending status** The site activates within 5–10 minutes of the first valid request. If it remains pending, confirm a request was actually sent (not a dry run), check that the Site ID in the URL matches the one in the dashboard, and verify the API key is correct. Use the verification cURL in Step 4 to test with a known bot user-agent. **Bot traffic is not being classified** Bot classification is derived entirely from the `user_agent` field. Confirm you are passing the raw, original user-agent string from the incoming request without modification. Check your log format — some CDNs normalize or truncate user-agent strings before writing them to logs. If so, use a logging integration that captures the original header. **Getting 422 errors** The most common cause is a missing required field or an incorrect type. Check that `timestamp` is a Unix epoch number (not ISO 8601), `status_code` is an integer (not a string), and `path` starts with a `/`. **NDJSON batches are being rejected** Each line must be a complete, valid JSON object with no embedded newlines. The `Content-Type` header must be exactly `application/x-ndjson`. Keep batch size under 1 MB uncompressed. **Don't see traffic after 10 minutes** Confirm your Webhook URL and API Key match exactly what's shown in your Scrunch app. Check that your `Content-Type` header matches the body format (`application/json` for single events, `application/x-ndjson` for batches). Confirm your `timestamp` is a Unix epoch in seconds, not milliseconds. *** ## Related * [Agent Traffic API Overview](/api-reference/agent-traffic/overview) — Full schema and response format for querying traffic data * [Get Agent Traffic](/api-reference/agent-traffic/get-agent-traffic) — Query aggregated bot traffic by date, path, and agent type * [CDN Integration Guides](/integrations/agent-traffic) — Native integrations for Cloudflare, Fastly, and other CDN platforms # Load a Data Mart from the Responses API Source: https://developers.scrunch.com/guides/data-mart-loading Incrementally load response-level data from the Scrunch Responses API, normalize it into fact and dimension tables, and compute metrics in your warehouse. Build a data mart from the Scrunch Responses API by incrementally loading response-level data, normalizing it into fact and dimension tables, and computing metrics in your warehouse. *** ## Prerequisites * A Scrunch API key with **Responses** access ([provision one here](/getting-started/authentication)) * A **brand ID** for the brand you want to load * A cloud data warehouse (BigQuery, Snowflake, Redshift, Databricks, etc.) *** ## How the Responses API works The Responses API returns one record per AI response. Each record includes the full response text, citations, brand and competitor evaluations, and prompt metadata. Key characteristics: * **1:1 response model** — each item represents a single, distinct AI response * **Denormalized** — arrays like `tags`, `key_topics`, `competitors`, `citations`, and `shopping_results` are embedded in each record * **Reverse chronological** — newest responses are returned first * **Supports date filtering and pagination** — ideal for incremental ETL > [!WARNING] > > **IDs are integers, not strings.** `id`, `prompt_id`, `persona_id`, and each competitor's `id` are all 64-bit integers. Type them as `INT64` / `BIGINT` in your warehouse rather than `STRING`, and be careful with JSON parsers that coerce large integers to floats — response IDs are already nine digits and will lose precision as a 32-bit int or a JavaScript `Number` past 2^53. Enum-like fields (`platform`, `brand_sentiment`, `brand_position`, `source_type`) are returned as **lowercase** strings. `stage` and `key_topics` are the exception — they are returned as display-cased names. For the full response schema, see the [Responses API overview](/api-reference/responses/overview). *** ## Incremental loading strategy Use date windows and pagination to pull new responses on a recurring schedule. **1. Choose your sync window** Use `start_date` and `end_date` (both `YYYY-MM-DD`, UTC) to define a date range. **`start_date` is inclusive and `end_date` is exclusive.** To load a single UTC day, set `end_date` to the *following* day — `start_date=2025-06-01&end_date=2025-06-02` returns exactly June 1. Treating `end_date` as inclusive is the most common cause of duplicated or missing days in a daily job. For daily loads, pull the previous UTC day after midnight to ensure completeness. **2. Paginate through all results** The API returns paginated results. Increment `offset` by `limit` until you have all records for the window. ```bash theme={null} curl "https://api.scrunchai.com/v1/$BRAND_ID/responses?start_date=2025-06-01&end_date=2025-06-02&limit=1000&offset=0" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` The response includes a `total` count so you know when you're done: ```json theme={null} { "total": 2430, "offset": 0, "limit": 1000, "items": [ ... ] } ``` `limit` defaults to **100**, so always set it explicitly for bulk loads. The minimum is 1 and no maximum is enforced — values well above 1000 are honored — but 1000 keeps individual requests cheap to retry. Keep `offset` a multiple of `limit`. **3. Deduplicate on id** Each response has a globally unique integer `id`. Use it as a natural key and upsert into your warehouse to handle re-runs or overlapping date windows. > [!NOTE] > > Some fields like `brand_present`, `brand_sentiment`, `tags`, `key_topics`, and `stage` may be re-evaluated if prompt metadata or brand configuration changes in Scrunch. Always upsert rather than append-only. `response_text`, `citations`, and `created_at` are immutable — they record exactly what was observed. ### Narrowing the window If you are backfilling a large history or building per-segment marts, these filters are available alongside the date range and reduce the volume you have to page through: | Parameter | Notes | | - | - | | `platform` | One of `chatgpt`, `claude`, `perplexity`, `google_ai_overviews`, `google_ai_mode`, `google_gemini`, `meta`, `copilot`, `grok` | | `prompt_id` | Integer — a single prompt | | `persona_id` | Integer — a single persona | | `stage` | Stage **name**, resolved against the brand's configured stages | | `has_shopping_data` | `true` returns only responses carrying shopping results, `false` only those without | > [!TIP] > > For a wide backfill, loop the window by day and by `platform` rather than requesting one enormous range. Pages stay small, retries are cheap, and a failure only costs you one day-platform slice instead of the whole job. *** ## Schema design Each API record includes arrays (`tags`, `key_topics`, `competitors`, `citations`, `shopping_results`) that should be normalized into separate tables to avoid row explosion. ``` responses (1 row per response) | |—— response_tags (1 row per response x tag) | |—— response_key_topics (1 row per response x key topic) | |—— response_competitors (1 row per response x competitor) | |—— response_citations (1 row per response x citation) | |—— response_shopping_results (1 row per response x product) ``` > [!TIP] > > If your warehouse has strong support for JSON or `ARRAY` columns (e.g., BigQuery, Snowflake, Databricks), you can skip the bridge tables and store `tags`, `key_topics`, `competitors`, `citations`, and `shopping_results` as native array or JSON fields directly on the responses table. Use `UNNEST` or `LATERAL FLATTEN` at query time instead of pre-normalizing. This simplifies your ETL at the cost of slightly more complex analytics queries. ### Responses fact table Store one row per response with scalar fields: | Column | Type | Notes | | - | - | - | | `id` | `INT64` | Primary key (globally unique) | | `created_at` | `TIMESTAMP` | When the response was captured (UTC) | | `prompt_id` | `INT64` | Foreign key to the prompt | | `prompt` | `STRING` | Text of the prompt | | `platform` | `STRING` | Lowercase slug — `chatgpt`, `perplexity`, `claude`, `google_ai_mode`, etc. | | `persona_id` | `INT64` | Nullable — prompts need not have a persona | | `persona_name` | `STRING` | Nullable | | `stage` | `STRING` | Stage **name**, not a fixed enum — see below | | `branded` | `BOOLEAN` | Whether the prompt explicitly mentions the brand | | `brand_present` | `BOOLEAN` | | | `brand_sentiment` | `STRING` | `positive`, `mixed`, `negative`, `none`, or `null` | | `brand_position` | `STRING` | `top`, `middle`, `bottom`, or `null` | | `country` | `STRING` | Nullable — 2-character ISO code | | `response_text` | `STRING` | Full AI-generated answer (markdown) | > [!WARNING] > > **`brand_sentiment` has four values, not three.** `none` means the brand was mentioned but without discernible sentiment — it is distinct from `null`, which means the brand was not mentioned at all. A `CASE` expression that maps only `positive`/`mixed`/`negative` will correctly leave `none` out of the sentiment average (this is what Scrunch does), but a `COALESCE(..., 50)` or an `ELSE 50` fallback will silently score every unsentimented mention as neutral and drag your numbers toward the middle. `stage` is **not** a fixed enum. Values resolve from the brand's own configured stages, so they vary per brand and can be renamed or extended. The default sets are intent (`Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other`) and funnel (`Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other`), but treat the column as free text and drive any stage dimension table off the values you actually observe rather than a hardcoded list. ### Optional scalar and semi-structured columns These fields are present on every record but are not needed by every mart: | Column | Type | Notes | | - | - | - | | `competitors_present` | `ARRAY` | Names of competitors mentioned. A convenience subset of `competitors` — skip it if you load the `response_competitors` bridge table | | `query_fanout` | `JSON` | Nullable. `{ queries: STRING[], engine_metadata: JSON }` — the searches the platform ran internally. Only populated for platforms that expose fan-out | > [!NOTE] > > `query_fanout` is null for most rows on most platforms. Store it as a raw JSON or `STRUCT` column rather than modelling it into its own table until you know you need it. ### Bridge tables Unnest each array into its own table, keyed by `response_id`. **response_tags** | Column | Type | Notes | | - | - | - | | `response_id` | `INT64` | | | `tag` | `STRING` | User-defined, free text | **response_key_topics** | Column | Type | Notes | | - | - | - | | `response_id` | `INT64` | | | `key_topic` | `STRING` | Display-cased topic name | > [!NOTE] > > `tags` and `key_topics` are distinct fields and are not interchangeable. Tags are arbitrary labels a user attaches to a prompt; key topics are Scrunch's topic classification. Both hang off the prompt rather than the response, so both can change on re-evaluation. **response_competitors** | Column | Type | Notes | | - | - | - | | `response_id` | `INT64` | | | `competitor_id` | `INT64` | Stable join key — prefer this over the name | | `competitor_name` | `STRING` | Display name; can be edited in Scrunch | | `present` | `BOOLEAN` | Always `true` in practice — see below | | `sentiment` | `STRING` | `positive`, `mixed`, `negative`, or `none` | | `position` | `STRING` | `top`, `middle`, `bottom` | > [!TIP] > > Key your competitor dimension on `competitor_id`. Competitor display names are editable in the Scrunch UI, so a mart joined on `competitor_name` will silently split one competitor into two rows the first time someone fixes a spelling. > [!WARNING] > > **The `competitors` array only contains competitors actually mentioned in the response.** It is not a row per configured competitor, and it is empty when no competitor was mentioned — so the array length varies from 0 to the number of competitors you track. Every entry carries `present: true`. > > This means **`response_competitors` does not give you a presence denominator.** Grouping it by competitor and dividing by its own row count yields 100% for every competitor. The denominator has to come from the `responses` table — see [Competitor metrics](#competitor-metrics) below. **response_citations** | Column | Type | Notes | | - | - | - | | `response_id` | `INT64` | | | `url` | `STRING` | Full cited URL | | `domain` | `STRING` | Registered domain extracted from `url` — provided for convenience | | `title` | `STRING` | Usually an **empty string** rather than null when the platform omits it — normalize with `NULLIF(title, '')` on load | | `snippet` | `STRING` | Nullable — not exposed by all platforms | | `source_type` | `STRING` | `brand`, `competitor`, or `other` (`other` is "third-party" in the Scrunch UI) | **response_shopping_results** Only populated for responses carrying product listings. Filter the load with `has_shopping_data=true` if this is all you need. | Column | Type | Notes | | - | - | - | | `response_id` | `INT64` | | | `url` | `STRING` | | | `title` | `STRING` | | | `image` | `STRING` | Nullable primary image; `all_images` holds the full array | | `description` | `STRING` | Nullable | | `rating` | `FLOAT64` | Nullable | | `reviews` | `INT64` | Nullable review count | | `purchasing_options` | `JSON` | Nullable nested array of seller/price options | > [!WARNING] > > Never unnest multiple arrays in the same query. Crossing two arrays (e.g., tags x competitors) causes row explosion and inflates every metric. *** ## Computing metrics Once your data mart is loaded, you can aggregate responses into daily performance summaries. Group on `DATE(created_at), prompt_id, prompt, platform` to match the way Scrunch reports prompt-level performance by default. The following examples use PostgreSQL syntax. Translate as needed for your warehouse. ### Response count ```sql theme={null} COUNT(*) AS responses ``` ### Brand presence percentage ```sql theme={null} COUNT(*) FILTER (WHERE brand_present = true)::float / NULLIF(COUNT(*)::float, 0.0) AS brand_presence_pct ``` ### Brand sentiment score ```sql theme={null} AVG( CASE WHEN brand_sentiment = 'positive' THEN 100 WHEN brand_sentiment = 'mixed' THEN 50 WHEN brand_sentiment = 'negative' THEN 0 ELSE NULL END ) AS brand_sentiment_score ``` ### Brand position score ```sql theme={null} AVG( CASE WHEN brand_position = 'top' THEN 100 WHEN brand_position = 'middle' THEN 50 WHEN brand_position = 'bottom' THEN 0 ELSE NULL END ) AS brand_position_score ``` > [!NOTE] > > Both score metrics are averaged **only over responses that mention the entity**. The `ELSE NULL` is doing that work: sentiment and position are `null` when the brand is absent, and `AVG` skips nulls. Keep the `ELSE NULL` — replacing it with a numeric default silently mixes non-mentions into the score. ### Citation rate Citation metrics are domain-based and independent of whether the brand was mentioned by name. Compute them from the `response_citations` bridge table, taking care to count *responses* rather than citation rows: ```sql theme={null} SELECT COUNT(DISTINCT c.response_id)::float / NULLIF((SELECT COUNT(*) FROM responses)::float, 0.0) AS citation_rate, COUNT(DISTINCT CASE WHEN c.source_type = 'brand' THEN c.response_id END)::float / NULLIF((SELECT COUNT(*) FROM responses)::float, 0.0) AS brand_citation_rate FROM response_citations c ``` > [!WARNING] > > "How many citations" has several defensible answers that differ by an order of magnitude on the same rows, so name the unit in every citation column you publish. Counting citation rows counts URL occurrences — one response citing a domain under four URLs contributes 4. Counting `DISTINCT response_id` contributes 1. Counting distinct `(response_id, domain)` pairs is what the Scrunch Citations dashboard's composition breakdown shows. Picking a different unit than the dashboard is the usual reason a mart's citation numbers won't reconcile. ### Putting it together ```sql theme={null} SELECT DATE(created_at) AS response_date, prompt_id, prompt, platform, COUNT(*) AS responses, COUNT(*) FILTER (WHERE brand_present)::float / NULLIF(COUNT(*)::float, 0.0) AS brand_presence_pct, AVG(CASE WHEN brand_sentiment = 'positive' THEN 100 WHEN brand_sentiment = 'mixed' THEN 50 WHEN brand_sentiment = 'negative' THEN 0 END) AS brand_sentiment_score, AVG(CASE WHEN brand_position = 'top' THEN 100 WHEN brand_position = 'middle' THEN 50 WHEN brand_position = 'bottom' THEN 0 END) AS brand_position_score FROM responses GROUP BY 1, 2, 3, 4; ``` These metric definitions match the ones used in the Scrunch dashboard and Query API. You can also define your own calculations if your use case requires it. ### Competitor metrics Sentiment and position translate directly, but **presence does not**. Because `response_competitors` only holds mentions, its own row count is the wrong denominator — you have to divide by the total response count for the period, which comes from the `responses` table: ```sql theme={null} WITH daily AS ( SELECT DATE(created_at) AS response_date, COUNT(*) AS responses FROM responses GROUP BY 1 ) SELECT d.response_date, rc.competitor_id, rc.competitor_name, COUNT(DISTINCT rc.response_id)::float / NULLIF(d.responses::float, 0.0) AS competitor_presence_pct, AVG(CASE WHEN rc.sentiment = 'positive' THEN 100 WHEN rc.sentiment = 'mixed' THEN 50 WHEN rc.sentiment = 'negative' THEN 0 END) AS competitor_sentiment_score FROM response_competitors rc JOIN responses r ON r.id = rc.response_id JOIN daily d ON d.response_date = DATE(r.created_at) GROUP BY d.response_date, rc.competitor_id, rc.competitor_name, d.responses; ``` Note that this emits no row for a competitor that went unmentioned on a given day, rather than a row reading 0%. If your dashboard needs explicit zeros, `LEFT JOIN` this result onto a date spine crossed with your competitor dimension. The brand equivalent does not have this problem: `brand_present` is a column on every response row, so `COUNT(*)` over `responses` is already the right denominator. ### Metrics you cannot reproduce from this API A few dashboard metrics depend on data the Responses API does not expose. Compute these with the [Query API](/api-reference/query/overview) instead of approximating them: > [!WARNING] > > The two APIs treat `end_date` differently: it is **exclusive** on Responses and **inclusive** on Query. Passing the same pair of dates to both compares an N-day window against an N+1-day one, which is a common reason a mart's numbers sit just below the dashboard's. * **`brand_avg_rank` / `competitor_avg_rank`** — first-occurrence mention rank is not a field on the response record. Note that `position` (`top` / `middle` / `bottom`) is a *thirds-of-the-response* bucket, not a rank, and is not a substitute for it. * **Share of voice** — normalized across the full tracked set, so it is only correct if your mart holds every tracked competitor for the period. * **`brand_citation_mention_rate`** — depends on crawled page content of the cited URLs, which is not part of the response payload. *** ## Related > [card] [Responses API Overview](/api-reference/responses/overview) > > Full schema, filtering, and pagination details. > [card] [Responses Quickstart](/getting-started/quickstart-responses) > > Make your first API call in cURL, Python, or JavaScript. # Optimize and Deploy Pipeline Lifecycle Guide Source: https://developers.scrunch.com/guides/orchestration-lifecycle Walk through every stage of the Optimize and Deploy pipeline — submitting URLs, tracking progress, polling status, handling errors, and processing results. > [!WARNING] > > The Optimize and Deploy API is currently in **early access**. Contact your Customer Success representative to get access enabled for your organization. ## Overview This guide walks through the complete lifecycle of an Optimize and Deploy pipeline — from submitting URLs to handling results. By the end, you'll understand how to track progress, handle errors, and integrate the pipeline into your workflow. ### Pipeline flow Each URL cascades through up to three stages. At every stage transition, a webhook fires so you can react in real time. Stages are optional — the pipeline exits early when the last enabled stage completes. Regardless of which stage is the final one, you always receive: 1. The **stage-specific webhook** for the last stage that ran (e.g., `audit.completed` if audit-only) 2. The **`pipeline.completed`** webhook once all URLs in the batch have finished ```mermaid theme={null} sequenceDiagram participant You participant API as Optimize & Deploy API participant Audit as 🔍 Site Audit participant Opt as ✨ Content Optimizer participant AXP as 🚀 AXP Deploy participant Hook as 🔔 Your Webhook You->>API: POST /orchestration/optimize-and-deploy/{brand_id} API-->>You: tokens[] + pipeline_id rect rgb(240, 248, 255) Note over Audit: Stage 1 — Always runs API->>Audit: Run audit for each URL Audit-->>API: Audit scores + checks API->>Hook: audit.completed (score, issues) Note over Hook: If optimize=false → pipeline ends here end alt optimize = true rect rgb(240, 255, 240) Note over Opt: Stage 2 — Only if optimize=true API->>Opt: Optimize content with prompts & personas Opt-->>API: Optimized title, description, content opt stage_axp = true API->>AXP: Stage optimized content (no live deploy) end API->>Hook: optimization.completed (optimization_run_id) Note over Hook: If neither deploy_axp nor stage_axp → pipeline ends here
If stage_axp=true → status="staged", pipeline ends here end end alt deploy_axp = true rect rgb(255, 248, 240) Note over AXP: Stage 3 — Only if deploy_axp=true API->>AXP: Deploy optimized content AXP-->>API: AXP version ID API->>Hook: deployment.completed (axp_version_id) end end rect rgb(245, 245, 245) Note over Hook: Always fires when all URLs finish API->>Hook: pipeline.completed (summary counts) end Note over You,API: Poll anytime with GET .../token You->>API: GET .../token API-->>You: Current status + results ``` ### Webhook events per configuration | Configuration | Webhooks fired (per URL) | Final webhook (per batch) | | - | - | - | | Audit only (default) | `audit.completed` | — | | Audit + optimize | `audit.completed` → `optimization.completed` | — | | Audit + optimize + stage (`stage_axp: true`) | `audit.completed` → `optimization.completed` (`status: "staged"`) | — | | Audit + optimize + deploy (`deploy_axp: true`) | `audit.completed` → `optimization.completed` → `deployment.completed` | `pipeline.completed` | `pipeline.completed` fires only for `deploy_axp: true` batches — other configurations end with the last per-URL webhook. ### What gets configured at each stage | Stage | Triggered by | Webhook event | Key data returned | | - | - | - | - | | **Site Audit** | Always runs | `audit.completed` | `score`, `issues`, `recommendations` | | **Content Optimizer** | `optimize: true` | `optimization.completed` | `optimization_run_id`, `title`, `description` | | **AXP Stage** | `stage_axp: true` + `site_id` | `optimization.completed` with `status: "staged"` | `optimization_run_id`, `title`, `description` | | **AXP Deploy** | `deploy_axp: true` + `site_id` | `deployment.completed` | `axp_version_id`, `site_id` | | **Pipeline done** | All URLs finish (`deploy_axp: true` batches only) | `pipeline.completed` | `completed_count`, `failed_count`, `total_count` | *** ## 1. Submit a pipeline ### Simple mode: shared configuration ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://example.com/page-a", "https://example.com/page-b"], "optimize": true, "target_prompts": ["best budget airlines", "cheap flights comparison"], "target_personas": [{"name": "Budget Traveler", "description": "Price-sensitive consumer"}] }' ``` ### Stage-only mode: review before going live Set `stage_axp: true` to run the full audit and optimize pipeline and push the optimized content to AXP as a staged change — without deploying a live version. Reviewers can then approve and publish from the Scrunch dashboard. ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://example.com/page-a"], "optimize": true, "stage_axp": true, "site_id": "01JEXAMPLE00000000000000" }' ``` The pipeline finishes at `orchestration_status: completed` after staging, and the final per-URL webhook is `optimization.completed` with `status: "staged"`. `stage_axp` and `deploy_axp` are mutually exclusive. ### Detailed mode: per-URL overrides ```bash theme={null} curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "requests": [ { "url": "https://example.com/budget-page", "target_prompts": ["best budget airlines"], "target_personas": [{"name": "Budget Traveler"}] }, { "url": "https://example.com/luxury-page", "target_prompts": ["luxury travel options"], "override_suggestions": true } ], "optimize": true, "deploy_axp": true, "site_id": "01JEXAMPLE00000000000000" }' ``` ### What gets returned ```json theme={null} { "pipeline_id": "01JPIPELINE000000000000", "tokens": [ {"token": "01JABC001", "url": "https://example.com/budget-page", "status": "pending", "orchestration_status": "audit"}, {"token": "01JABC002", "url": "https://example.com/luxury-page", "status": "pending", "orchestration_status": "audit"} ], "status": "pending" } ``` `pipeline_id` is only set when `deploy_axp` is true — it groups all URLs into a single AXP deployment batch. *** ## 2. Track progress ### Option A: Polling ```bash theme={null} curl "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234/01JABC001" \ -H "Authorization: Bearer $SCRUNCH_API_KEY" ``` | `orchestration_status` | Meaning | | - | - | | `audit` | Page audit running | | `optimizing` | Content optimization running | | `deploying` | AXP deployment running | | `completed` | All stages finished successfully | | `failed` | Pipeline stopped at the failing stage | > [!TIP] > > Poll every 5–10 seconds. Audits typically complete in under 30 seconds; optimization may take 1–2 minutes depending on page complexity. ### Option B: Webhooks Configure a webhook URL for your brand and receive HTTP callbacks at each stage transition. > [card] [Webhook setup guide](/api-reference/webhooks/overview) > > Configure webhooks and verify signatures. *** ## 3. Handle stage transitions ### Audit → Optimizing ```json theme={null} { "orchestration_status": "optimizing", "result": { "access_controls_score": 100, "content_delivery_score": 90, "content_quality_score": 85 } } ``` ### Optimizing → Deploying ```json theme={null} { "orchestration_status": "deploying", "optimization_run_id": "01JOPTRUN0000000000000" } ``` ### Deploying → Completed ```json theme={null} { "orchestration_status": "completed", "axp_version_id": 42 } ``` *** ## 4. Handle errors | Prefix | Stage | | - | - | | `ORCH-INIT-*` | Request validation | | `ORCH-AUDIT-*` | Page audit | | `ORCH-OPT-*` | Content optimization | | `ORCH-DEPLOY-*` | AXP deployment | | `ORCH-HOOK-*` | Webhook delivery | | Code | Cause | Fix | | - | - | - | | `ORCH-INIT-004` | URL domain doesn't match the registered site | Ensure all URLs belong to the site's domain | | `ORCH-AUDIT-002` | Page fetch failed (404, timeout, blocked) | Verify the URL is accessible and not blocked by robots.txt | | `ORCH-OPT-002` | No content available to optimize | Ensure the page has substantial text content | | `ORCH-DEPLOY-002` | Site not found for the given site_id | Verify the site_id is correct and belongs to your brand | *** ## 5. Full working example ```python theme={null} import requests import time API_KEY = "your-api-key" BRAND_ID = 1234 SITE_ID = "01JEXAMPLE00000000000000" BASE = f"https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/{BRAND_ID}" HEADERS = {"Authorization": f"Bearer {API_KEY}"} urls = [ "https://example.com/page-a", "https://example.com/page-b", "https://example.com/page-c", ] resp = requests.post(BASE, headers=HEADERS, json={ "urls": urls, "optimize": True, "deploy_axp": True, "site_id": SITE_ID, }, timeout=30) resp.raise_for_status() pipeline = resp.json() print(f"Pipeline started: {pipeline.get('pipeline_id')}") pending = {r["token"]: r["url"] for r in pipeline["tokens"]} while pending: for token in list(pending.keys()): status = requests.get(f"{BASE}/{token}", headers=HEADERS, timeout=30).json() stage = status["orchestration_status"] if stage in ("completed", "failed"): result = "OK" if stage == "completed" else "FAILED" print(f" [{result}] {pending[token]}") if status.get("axp_version_id"): print(f" AXP version: {status['axp_version_id']}") del pending[token] if pending: time.sleep(5) ``` *** ## 6. Viewing results in the Scrunch dashboard Everything the pipeline does is visible in the Scrunch dashboard — exactly as if each step had been performed manually. * **Site Audit results** — **Your Brand → Site Audits** * **Content Optimizer results** — **Your Brand → Optimizer → History** * **AXP deployments** — **Your Brand → AXP → \[site] → Version History** > [!TIP] > > To roll back a deployment, use the **Redeploy** option on any previous version in the AXP version history. *** ## Best practices * **Use webhooks for production** — more efficient and lower latency than polling * **Handle partial failures** — in a batch, some URLs may succeed while others fail; check each token individually * **Set `override_suggestions: true` carefully** — only your explicitly provided prompts and personas are used * **Start with audit-only** — validate URLs and check audit scores before committing to optimization and deployment > [card] [Orchestration API reference](/api-reference/optimize-deploy) > > Endpoint details, error codes, and schema reference. > [card] [Webhooks reference](/api-reference/webhooks/overview) > > Event types, payload schemas, and signature verification. # Build with Scrunch Source: https://developers.scrunch.com/index Use Scrunch APIs, the MCP, or Data Studio integrations to query AI visibility data, automate configuration, and power custom reports. ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_quickstart_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=7bd97bb719b0687e125484f62fefe21d) ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_quickstart_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=7bd97bb719b0687e125484f62fefe21d) [Open](/getting-started/quickstart-query) QuickstartMake your first API request and get brand presence data in minutes. ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_mcp_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=5b0a5ec83137d19cf49dda8a95fa5ea3) ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_mcp_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=5b0a5ec83137d19cf49dda8a95fa5ea3) [Open](/mcp/overview) Scrunchie MCPConnect your Scrunch data to Claude, ChatGPT, and other AI assistants — no code required. ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_api-ref_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=e73c5bf47dc95e0cf30ad8e4c8c85e58) ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_api-ref_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=e73c5bf47dc95e0cf30ad8e4c8c85e58) [Open](/api-reference/introduction) API ReferenceExplore all available endpoints for Query, Responses, Agent Traffic, and Configuration. ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_data-studio_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=88b221df87652bb3ada3a87bfed4e0fc) ![](https://mintcdn.com/scrunchai/7QAb9haAyfxFwFlB/images/api_docs_data-studio_v2.png?fit=max\&auto=format\&n=7QAb9haAyfxFwFlB\&q=85\&s=88b221df87652bb3ada3a87bfed4e0fc) [Open](/integrations/data-studio-connector) Data StudioVisualize Scrunch data in pre-built Looker Studio dashboard templates. # Connect Your CDN to Scrunch Agent Traffic Source: https://developers.scrunch.com/integrations/agent-traffic Stream AI crawler and bot access logs from supported CDNs and hosting platforms into Scrunch Agent Traffic to track which pages AI bots visit and why. Scrunch Agent Traffic shows which AI crawlers are visiting your site, which pages they hit, and why they came. To enable this data, your CDN or hosting platform must expose access logs that Scrunch can classify. This page serves as the entry point for CDN setup instructions. Because each platform requires different configuration steps, the full integration guides live in our Help Center. > [card] [View CDN Setup Instructions](https://intercom.help/scrunchai/en/collections/15678483-agent-traffic) > > Open Agent Traffic Setup Guides ## Overview Agent Traffic works by securely reading log data from your CDN or hosting provider. We support native integrations for several major platforms, along with recommended workarounds when providers do not expose request logs directly. Supported platforms include: * Modern CDNs * Serverless hosting providers * Enterprise-grade logging platforms > [!NOTE] > > The exact list of supported integrations may change as we continue expanding platform coverage. Always refer to the Help Center for the most up-to-date instructions. ## What You'll Find in the Help Center Our Help Center includes: * Step-by-step setup instructions for each supported CDN or hosting provider * Code snippets where applicable (for Workers, Logpush, Vercel drains, etc.) * Required fields and log formats * Validation steps to confirm logs are flowing into Scrunch * Workarounds for platforms that do not provide direct log access Each integration guide walks you through enabling Scrunch in just a few minutes. ## Typical CDN Options While the full list is maintained in the Help Center, Scrunch includes integrations for: * Popular serverless edge platforms * Enterprise-level CDN logging products * Hosting environments used by agencies and mid-market teams * Workarounds for CMSs or hosting tools with limited log visibility These options ensure that nearly all Scrunch customers—regardless of their tech stack—can enable Agent Traffic reliably. ## Where to Go From Here > [card] [CDN Setup Guides](https://intercom.help/scrunchai/en/collections/15678483-agent-traffic) > > Find detailed instructions for your hosting provider. > [card] [Contact Support](mailto:support@scrunchai.com) > > Need help with an unsupported CDN or advanced setup? Our team can assist. # Install the Scrunch Data Studio Connector (v2) Source: https://developers.scrunch.com/integrations/data-studio-connector 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](/integrations/looker-studio). # 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](/integrations/data-studio-troubleshooting). > [!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. # Data Studio Dashboard Templates for Scrunch Source: https://developers.scrunch.com/integrations/data-studio-templates Copy pre-built Looker Studio dashboards for multi-brand visibility, single-brand performance, and AI agent traffic and connect them to your Scrunch data. # Dashboard Templates Choose a pre-built template to get started quickly. Make a copy and connect it to your Scrunch data source. > [card] [Overview Dashboard](https://lookerstudio.google.com/reporting/f01e23ae-aecb-4449-a185-6c6e599acfb8) > > Multi-brand visibility overview with presence, position, and sentiment. > [card] [Single-Brand Dashboard](https://datastudio.google.com/reporting/5d98cb14-066d-468d-b30e-8e0b5e594ebc) > > Deep dive into a single brand's visibility, sentiment, and competitive performance. > [card] [Agent Traffic Dashboard](https://datastudio.google.com/u/0/reporting/fbfb64fa-bb52-4ab3-8aaf-bf1468a3bf2c) > > See which AI bots are crawling your site, how often, and which pages they target. > [card] [AI Referrals](https://datastudio.google.com/reporting/56d78ec1-be14-474f-9542-43b78e13acf1) > > Measure human referral traffic to your site from AI sources like chatgpt.com and perplexity.ai. ## How to Use a Template **1. Install the connector first** Make sure you've already installed and configured the v2 connector. See the [Data Connector](/integrations/data-studio-connector) guide. **2. Open a template** Select a template from the gallery above and open it. **3. Make a copy** In the top-right corner, click the **three dots** → **Make a copy**. When prompted, select the Scrunch data source you configured earlier. ![source configuration](https://mintcdn.com/scrunchai/JDuEgo9g0FRHbTd-/images/spirit-copy.png?fit=max\&auto=format\&n=JDuEgo9g0FRHbTd-\&q=85\&s=793c47d8351653548b9137f802c75981) **4. Customize your dashboard** You can now modify charts, add filters, or blend additional data sources like GA4, CRM data, or paid media. ![Image](https://mintcdn.com/scrunchai/2FdwxvqXHl25c2w-/images/image.png?fit=max\&auto=format\&n=2FdwxvqXHl25c2w-\&q=85\&s=cbe7b432bf5bc1e11a1418ff9bd3f8d5) # Troubleshoot the Scrunch Data Studio Connector Source: https://developers.scrunch.com/integrations/data-studio-troubleshooting FAQs, error fixes, and reset instructions for the Scrunch Data Studio connector covering brand IDs, agent traffic charts, date grouping, and auth issues. # Troubleshooting This page covers the issues we hear about most often when customers connect Scrunch data to Looker Studio (formerly Data Studio). It's written for marketing teams, not engineers — but every section ends with enough detail to share with a developer or paste into an AI assistant if you get stuck. If you hit an error inside a chart, the message itself tells you what to do. Each one ends with a "Diagnostic details" line you can copy and share with support or paste into Claude / ChatGPT to get more help. *** ## When a chart shows an error message The connector now surfaces real errors directly inside your chart instead of silently showing "No data." Match the message you're seeing to the right section below. #### **404, invalid values, or wrong brand data** > **Error examples**\ > You may see one or more of the following errors in a Scrunch Looker Studio report:\ > `Exception: Request failed for https://looker-api.scrunchai.com returned code 404`\ > You may also see references like: `getBrandData:236` or `getData:194`\ > Or chart-level errors such as: `Invalid values`\ > \ > **What this usually means**\ > This usually means Looker Studio is trying to request Scrunch data for a Brand ID that the connector cannot retrieve.\ > \ > Common causes include: > > 1. The data source is configured with the wrong default Brand ID. > 2. The Brand ID parameter override in the report is missing, invalid, or no longer allowed. > 3. The API key was deleted, regenerated, or rescoped through Scrunch (see [here](/getting-started/authentication)). > 4. A copied report is still pointing to a previous client's data source or Brand ID. > 5. The connector was reconnected and the report-level or chart-level Brand ID overrides were invalidated. > > This is usually a data source / connector configuration issue as opposed to a chart design issue.\ > \ > **How to fix**\ > The person fixing this needs edit access to the Data/Looker Studio *data source*, not just the report. > > 1. Open the affected Data Studio report. > 2. Identify the Scrunch AI data source used by the broken charts. > 3. Open the Scrunch AI data source. > 4. Go to `Edit connection`. > 5. Confirm that the API key is valid. > 6. Confirm that the Brand ID(s) are correct. > 7. Confirm that the API key is scoped to **Query** and has access to the intended brand through Scrunch. > 8. If the report relies on report-level, page-level, group-level, or chart-level Brand ID overrides, make sure `Allow "Brand IDs" to be modified in reports` is checked. > 9. Click `Reconnect`. > > ![Image](https://mintcdn.com/scrunchai/2FdwxvqXHl25c2w-/images/image.png?fit=max\&auto=format\&n=2FdwxvqXHl25c2w-\&q=85\&s=cbe7b432bf5bc1e11a1418ff9bd3f8d5) > > **Why Brand ID configuration matters**\ > The Scrunch Looker Studio connector pulls data for a specific Scrunch brand. During connector setup, users are prompted to enter a Brand ID, and the current connector supports pulling data for one brand at a time.\ > \ > Scrunch API tokens can be scoped to one or more brands or to an organization, but almost all API calls require a specific Brand ID. The Query API is the API used for reporting and BI workflows.\ > \ > Data/Looker Studio Community Connectors can expose overridable parameters. If the connector allows a parameter to be modified in reports, editors can override the default value at the report, page, group, chart, or control level. **"We couldn't load your agent traffic data right now…"** > This means Scrunch's Agent Traffic API returned an error for the brand(s) on this chart. Usually short-lived. > > **Try in this order:** > > 1. **Wait about a minute and refresh the chart.** Many of these errors clear on their own. > 2. **If the chart breaks down data by `Path` or `Agent Source`, shorten the date range.** Try 1 to 3 days. For high-traffic brands, those breakdowns become slow to aggregate over long ranges and can time out. > 3. **Use the connector's `Path Filter` setting** to narrow the chart to a single section of your site like `/blog/`. (See [How to edit a data source connection](#how-to-edit-a-data-source-connection) below.) > > If you keep seeing this on every refresh for the same brand even with a short date range, check whether the brand's Site ID is correct (see [Agent traffic charts won't load at all](#agent-traffic-charts-won-t-load-at-all)). **"This chart is grouping agent traffic by Path / Agent Source across a date range that's too big…"** > This is the same kind of error as above, but the connector recognized that you're using a Path or Agent Source breakdown and tailored its suggestions: > > 1. **Shorten the date range.** This is the fastest fix. Try 1-3 days first; expand from there. We've confirmed a chart breaking down \~21,000 daily agent requests by Path loads cleanly at 1 day but times out at 7 days. > 2. **Add a `Path Filter`** to scope the chart to a section. Combines well with #1. > 3. **Split one large chart into several smaller ones**, each filtered to a different section. **"We couldn't load your AI visibility data right now…"** > Same idea as the agent traffic error, but for the Query API (brand presence, citations, sentiment, etc.). Wait a minute, refresh, and if it persists, the diagnostic line in the message includes the brand ID and HTTP status — share that with support. **"This chart is asking for two kinds of data at once…"** > You've mixed brand visibility metrics (`Brand Presence`, `Brand Sentiment`, etc.) with agent traffic metrics (`Agent Requests`, `Agent Source`, etc.) in the same chart. These come from different parts of Scrunch and can't share a chart. > > **Fix:** Build a separate chart for each kind of data. One chart for the visibility metric, a second chart for the agent traffic metric. **"Agent traffic data isn't available by month yet"** > The Agent Traffic API supports daily and weekly aggregation, but not monthly. > > **Fix:** Change the chart's date dimension to `Date Week` (weekly) or `Date` (daily). **"This data source doesn't have a Scrunch API key yet"** > Click the **pencil icon** next to the data source in Looker Studio (or **Edit connection**), paste your Scrunch API key, and save. > > You can find your key at: **app.scrunchai.com → Organization → Settings → API Keys**. **"This data source needs at least one brand ID"** > Same fix path — click the pencil, then add brand IDs. Separate multiple with commas (e.g., `1234,5678,9012`). > > A brand's ID is the number after `/b/` in its Scrunch URL — e.g., `1234` in `app.scrunchai.com/org/.../b/1234/dashboard`. **"This chart uses agent traffic data, but the data source doesn't have a Site ID yet"** > See [Agent traffic charts won't load at all](#agent-traffic-charts-won-t-load-at-all) below. *** ### Charts say "No data" with no error message If the chart isn't showing an error, the connector got a successful response — there's just no data to display. Common causes: #### **The date range is outside the last 90 days** > Scrunch's Query API only returns data for the **last 90 days**. If your report's date range starts further back than that, your visibility charts will be empty. > > * **Fix:** Set the report or chart date range to a window within the last 90 days. The built-in "Last 30 days" / "Last 90 days" presets work well. #### **The chart filter is too restrictive** > A `branded = false` filter, a competitor that wasn't tracked during the date range, or a tag that doesn't exist will all return zero rows. ![Screenshot 2026 05 16 At 12 11 17 PM](https://mintcdn.com/scrunchai/794rh0IJqkUIwzoN/images/Screenshot-2026-05-16-at-12.11.17-PM.png?fit=max\&auto=format\&n=794rh0IJqkUIwzoN\&q=85\&s=41b8efd52a329d3224dd5e087dbf446c) #### **Branded vs. non-branded prompts** > By default, the Scrunch dashboard filters to non-branded prompts. If you set up a chart with the same filter and your figure in the Scrunch app includes branded prompts (or vice versa), the numbers will look different. > > * **Fix:** Add a `Branded` filter to the chart and set it to match what you want — `false` for non-branded only, `true` for branded only, or remove the filter to include both. #### **The chart's per-chart data source is wrong** > Looker Studio lets every chart override the report-level data source. If a chart was copied from a template, its **per-chart data source** might still point to the original (broken) connector, even though you've already set the report-level data source correctly. > > * **Fix:** Click the chart → look in the right-hand panel under **Setup** → **Data source**. If it shows anything other than your Scrunch data source, click it and swap. ![Screenshot 2026 05 16 At 12 10 16 PM](https://mintcdn.com/scrunchai/794rh0IJqkUIwzoN/images/Screenshot-2026-05-16-at-12.10.16-PM.png?fit=max\&auto=format\&n=794rh0IJqkUIwzoN\&q=85\&s=cbb136c1dbdc35be0f4afc72fe40b546) *** ### Agent traffic charts won't load at all > Agent traffic charts need three things to work: > > 1. A valid **API key** on the data source. > 2. One or more **brand IDs** that your API key can read. > 3. A **Site ID** for each brand whose agent traffic you want to chart. > > The first two errors above are caught and shown clearly. The third one — Site ID — is also surfaced as an error now, but if you're seeing empty charts after configuring a Site ID, double-check the value. > > **Where to find a Site ID:** > > 1. Open the brand in Scrunch. > 2. Navigate to **Agent Traffic**. > 3. Look in the URL — the Site ID is the long string after `/site/` (e.g., `01KCHAEBS552AC5G1Z454E1AG2`). > 4. Paste it into the data source's **Site ID** field. > > The Site ID must belong to a brand your API key can access. If you have multiple brands, you currently configure one Site ID per data source — if you need agent traffic for multiple brands in one report, create a second data source for each. *** #### **"To fix this chart: remove / swap ..." — fields that can't be combined** > Scrunch calculates some fields in ways that cannot be mixed in one chart. Rather than letting the API return a raw error, the connector checks the combination first and tells you which field to change. These are the ones you're most likely to hit. > > | What you built | Why it can't work | The fix | > | - | - | - | > | `Source Type` with any citation metric | `Source Type` is only available on a different calculation path from citation metrics | Swap it for **`Citation Owner`** — same brand / competitor / other split | > | `Competitor Name` or `Competitor ID` with any citation metric | Same reason | Swap it for **`Cited Competitor`** | > | `Source Domain (legacy)` with any citation metric | Same reason | Swap it for **`Citation Domain`** | > | `AI Platform Search Enabled` with any citation metric | Same reason | Remove it from the chart | > | A cited-source breakdown with **both** a citation metric and a per-response metric (e.g. `Citation Domain` + `Responses` + `Citation Rate (%)`) | One counts cited pages, the other counts AI responses, and one response can cite many pages — totalling both in one table would double-count | Keep one kind. Use the citation metrics for a source breakdown, or drop the source dimension | > | `Influence Score` without a source breakdown | Influence Score ranks an individual cited source, so the chart has to say which source each score belongs to | Add **`Citation Domain`** or **`Source URL`** | > | `Source Topic` or `Citation Segment` with a per-response metric | Both describe cited sources, so they only work with citation metrics | Swap the metric for `Citation Count` or `Citation Rate (%)` | > | A date dimension on a **Site Map** chart | The site map is a snapshot of your pages as they are now, not a history | Remove `Date` / `Date Week` | > | `Date` or `Date Week` on a **Signals** chart | Signals carry their own date | Use **`Signal Date`** instead | > > > [!TIP] > > > > If a metric you didn't add is named in the message, check the chart's metric list — Looker Studio puts a metric into every new table automatically, so it is often left over from when the chart was created. *** ### **After making a copy of a template** > When you copy a Scrunch Looker Studio template into your own account, you'll see one or more data sources labeled **Unknown** under the report. That's expected — Looker Studio can't share the original Scrunch data source across accounts, so it shows the placeholder until you swap in your own connection. > > **Fix:** > > 1. Open the copied report. > 2. Click **Resource** → **Manage added data sources**. > > ![Screenshot 2026 05 16 At 12 09 16 PM](https://mintcdn.com/scrunchai/794rh0IJqkUIwzoN/images/Screenshot-2026-05-16-at-12.09.16-PM.png?fit=max\&auto=format\&n=794rh0IJqkUIwzoN\&q=85\&s=bae062062c7f56db642039934ca972e0) > 3. For each "Unknown" entry, click **Edit** → Looker will prompt you to pick a replacement. Choose your Scrunch data source. > 4. Save. > > Some templates have **per-chart** data sources in addition to the report-level one. After fixing the report-level data source, check a few charts — if they still show "Unknown" or "No data," edit the chart and update its data source the same way (see [The chart's per-chart data source is wrong](#the-chart-s-per-chart-data-source-is-wrong)). *** ### How to track brand citation rate > Use the **`Brand Citation Rate (%)`** field. It ships with the connector — no calculated field needed. > > If you don't see it, your data source is on an older field list. [Refresh the fields](/integrations/data-studio-connector#keeping-your-connector-up-to-date) and it will appear. > > **Citation rate and mention rate are different measures, and mixing them up is the most common source of confusion here:** > > * **`Mention Rate`** (formerly `Brand Presence (%)`) — the share of AI responses whose **text** names your brand. A citation of your domain does **not** count toward it. > * **`Brand Citation Rate (%)`** — the share of AI responses that **cite a page on a domain you own**, whether or not the response names you. > > A response can do either, both, or neither. If you need the full citation picture, the connector also has `Citation Count`, `Citation Unique Domains`, `Brand Citation Share of Voice (%)`, and an `Influence Score` for ranking individual cited pages. *** ### A chart loads partly, then stops > This happens on charts pulling lots of data. Looker Studio gives the connector a fixed time budget per chart; if it runs out before all the rows arrive, the chart can render partially or skip the rest. > > **What works:** > > 1. **Set a custom date range on the chart** that's narrower than the report's range. Smaller fetch, completes in time, gets cached. > 2. **Refresh the report.** The first attempt may have failed; subsequent attempts read from cache and finish. > 3. **Avoid combining several high-cardinality breakdowns** in one chart (e.g. `Path` + `Agent Source` + `Date` together). Pick one breakdown and use filters to narrow the others. *** ### Why the same chart errored a minute ago and is error-free now (or vice versa) > When the connector hits an API error for a specific brand, it remembers that failure for **60 seconds** and returns the cached error instantly for any chart that asks for the same data during that window. This protects Scrunch's API from being hammered while it recovers and gives you fast feedback that something is still wrong. > > After 60 seconds, the connector tries again. If the underlying issue cleared, the chart loads normally. If not, you'll see the same error message. > > This is why hitting refresh repeatedly during an outage looks like nothing is happening — you're hitting the cached error each time. Wait a full minute between refreshes for the connector to retry. *** ## When the numbers look wrong (but aren't) Two behaviours surprise people often enough to be worth stating plainly. #### **A scorecard doesn't match the number in Scrunch** > Rates like `Mention Rate`, `Citation Rate (%)`, the share-of-voice fields, and the 0–100 scores are **averages**. When Looker Studio rolls several rows into one number — a scorecard sitting on top of daily rows, for instance — it averages those rows **evenly**, while Scrunch computes the true volume-weighted figure. A day with 5 responses then counts the same as a day with 4,000. > > On a brand with 37 collection days the gap measured 0.37 percentage points; it widens as daily volumes get more uneven. > > **The fix:** for an exact figure over a window, build the chart with **no date dimension**. The connector then asks Scrunch for a single pre-aggregated number instead of averaging rows in Looker. *** #### **Signal counts look too high** > Signals re-fire every night they are still detected, so a 30-day range contains the same underlying issue once per night it was detected — `Signal Count` counts detections, not distinct issues. > > **The fix:** filter `Signal Is Latest Detection` to `true` for a count of distinct issues, or count unique values of `Signal Fingerprint`. *** ## How to edit a data source connection If an error message tells you to "edit the data source," here's the path in Data/Looker Studio: **1. Open the report in edit mode** Click **Edit** in the top right corner. ![Screenshot 2026 05 16 At 12 07 52 PM](https://mintcdn.com/scrunchai/794rh0IJqkUIwzoN/images/Screenshot-2026-05-16-at-12.07.52-PM.png?fit=max\&auto=format\&n=794rh0IJqkUIwzoN\&q=85\&s=3a4fba16a24b23542d022c2e2a549e9f) **2. Open the data sources panel** Click **Resource** → **Manage added data sources** ![Screenshot 2026 05 16 At 12 08 15 PM](https://mintcdn.com/scrunchai/794rh0IJqkUIwzoN/images/Screenshot-2026-05-16-at-12.08.15-PM.png?fit=max\&auto=format\&n=794rh0IJqkUIwzoN\&q=85\&s=42b6d42380e0d7f63ab91bf7cdfe9afe) **3. Edit the Scrunch data source** Find your Scrunch data source in the list and click **Edit** on the right. **4. Update connection settings** The connector configuration screen opens. Update the API Key, Brand IDs, Site ID, or Path Filter as needed, then click **Reconnect** in the top right. ![Screenshot 2026 05 20 At 10 08 25 AM](https://mintcdn.com/scrunchai/kwWis3w6sdGGQJxg/images/Screenshot-2026-05-20-at-10.08.25-AM.png?fit=max\&auto=format\&n=kwWis3w6sdGGQJxg\&q=85\&s=d5bebc7320da919830ce6ff83efe0465) **5. Apply changes** When prompted, click **Apply** to push the updated configuration to all charts using this data source. *** ## How to read the diagnostic details in an error message Every connector error ends with a `Diagnostic details for reference:` block. The pieces: * `API="…"` — which Scrunch API failed (`"Query API"` or `"Agent Traffic API"`) * `brand=…` — the brand ID that returned the error * `status=…` — the HTTP status code (5xx = Scrunch backend issue, 4xx = config/auth issue) * `body="…"` — a short snippet of the API's error response * `fields="…"` — the fields the chart asked for (in newer messages; helps identify high-cardinality timeouts) If you need help, you can paste the whole error message — including the diagnostic line — into Claude or ChatGPT and they can usually point you to the cause. Or share it with Scrunch support (the diagnostic line is the most useful part). *** ## FAQs **Can I use this with just one brand?** > Yes. Enter a single Brand ID and the connector works exactly like the older single-brand connector, with the added benefit of comparison fields, agent traffic support, and clearer error messages. **Does Agent Traffic support weekly date grouping?** > Yes. Use `Date Week` as the chart's date dimension and the connector aggregates by week automatically. (Monthly is not supported by the Agent Traffic API yet.) **Are there limits to dashboard size?** > Looker Studio allows a maximum of 30 concurrent Community Connector queries. Each chart counts as one query. Reports with more than \~15-20 Scrunch-powered charts may load slowly or hit the limit. If you need a large dashboard, consider splitting it across multiple report pages — Looker only loads the visible page. **How do I compare last week vs. previous week?** > Use Looker Studio's built-in date comparison feature (in the date range control), or create a calculated field like: > > ```text theme={null} > CASE > WHEN DATE_DIFF(CURRENT_DATE(), date, DAY) < 7 THEN brand_presence_percentage > END > ``` *** ## Resetting your connector If something goes wrong and you want to start fresh: **1. Open Data Sources** Go to [Looker Studio](https://lookerstudio.google.com/navigation/reporting) and click **Data Sources** in the top navigation. ![Data Sources reset](https://mintcdn.com/scrunchai/b71mw_jtaA4t2Jw5/images/data-sources-reset-1.png?fit=max\&auto=format\&n=b71mw_jtaA4t2Jw5\&q=85\&s=dc87928212ead79ff68017ff307c2736) **2. Remove the Scrunch data source** Find your Scrunch data source → click the three dots → **Remove**. ![Screenshot 2026 05 13 At 11 40 33 PM](https://mintcdn.com/scrunchai/b71mw_jtaA4t2Jw5/images/Screenshot-2026-05-13-at-11.40.33-PM.png?fit=max\&auto=format\&n=b71mw_jtaA4t2Jw5\&q=85\&s=7cfc45c1ebec8cdb1dea9b4779f33e08) **3. Revoke the connector** Click **+ Create** → **Data source** → Scroll down to find the Scrunch connector under **Partner Connectors** → click the three dots → **Revoke**. ![Screenshot 2026 05 16 At 10 59 18 AM](https://mintcdn.com/scrunchai/qqJtpe9vXEBcw8hT/images/Screenshot-2026-05-16-at-10.59.18-AM.png?fit=max\&auto=format\&n=qqJtpe9vXEBcw8hT\&q=85\&s=2cc89ae6037fe46ee0e9b9dd5621d35a) ![Screenshot 2026 05 16 At 11 00 37 AM](https://mintcdn.com/scrunchai/qqJtpe9vXEBcw8hT/images/Screenshot-2026-05-16-at-11.00.37-AM.png?fit=max\&auto=format\&n=qqJtpe9vXEBcw8hT\&q=85\&s=7a4d5ae2a369516d9890b6325e28b189) **4. Reinstall** Use the [connector install link](https://datastudio.google.com/datasources/create?connectorId=AKfycbyi7ba5UXYeYqau1m6upcPFRBm2n0z49C5fg3dSwdbdFArz2IjLbCBc05HcNsoMpLFOcQ) to start fresh. # Looker Studio Legacy Single-Brand Connector Source: https://developers.scrunch.com/integrations/looker-studio Configure the legacy single-brand Scrunch Looker Studio Community Connector to build dashboards and blend brand visibility metrics with GA4 and other sources. # Looker Studio Connector (Legacy) > [!NOTE] > > **Connector last updated:** September 14, 2026 — this release fixes a date-handling bug that could stop charts loading, and adds citation, share-of-voice, and rank fields. > > Already using it? [Refresh your data source](/integrations/data-studio-connector#keeping-your-connector-up-to-date) to pick up the new fields — the steps are the same for this connector, and your existing dashboards keep working exactly as they are. > [!NOTE] > > **We recommend moving to the v2 connector.** This legacy connector handles one brand per data source. The [Data Studio Connector](/integrations/data-studio-connector) connects 1–30+ brands in a single data source, adds agent traffic, site map, and signals data, and fetches every brand in parallel with smarter caching — noticeably faster once you are running more than one brand. This page stays supported for existing setups. Connect Scrunch to Google Looker Studio using our private Community Connector. This allows you to build dashboards, analyze historical performance, and blend Scrunch metrics with other data sources such as GA4. ![Hero Pn](https://mintcdn.com/scrunchai/67YuQjB0mGKJxVaT/images/hero.png?fit=max\&auto=format\&n=67YuQjB0mGKJxVaT\&q=85\&s=9603c3e505bf69578b6bf79b6ea8c584) The connector exposes all standard Scrunch Query API fields, including: * Brand presence, position, and sentiment * Competitor presence metrics * Date, platform, persona, tag, and source dimensions Once connected, you can create fully custom dashboards or use our pre-built Scrunch Looker Studio template. ## Install the Scrunch Looker Studio Connector The connector is not yet in the public gallery. Install it directly using the link below: > [card] [Install Connector](https://lookerstudio.google.com/datasources/create?connectorId=AKfycbzRRK2rRqh1_ujHS313hitMb5PopzgNUS5m5ih6ohI) > > Open the Scrunch AI Looker Studio Connector This installs the Scrunch AI data source inside Looker Studio for your Google account. ## Authenticate With Your Scrunch API Key During setup, Looker Studio will prompt you for: 1. **Your API key** > You can provision a Query-scoped API key from: > > **Scrunch** → **Organization** → **Settings** → **API Keys** > > > [!NOTE] > > > > A single API key may be scoped to one or many brands. Use narrow scoping when integrating with client-facing dashboards. 2. **Your Brand ID** > The connector loads data for one brand at a time. > > To find your brand ID: > > Open the brand's dashboard in Scrunch > > Look at the URL: > > `https://app.scrunchai.com/org/.../b/1234/dashboard` > > Here, 1234 is your Brand ID. > > > [!NOTE] > > > > If you need multi-brand dashboards, reach out to Scrunch. We are collecting feedback for expanded multi-brand support. ## Supported Dimensions and Metrics This connector covers a single brand and exposes **65 fields** from the Scrunch Query API. > [accordion] Dates (5) > > | Field | ID | Type | Notes | > | - | - | - | - | > | 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. | > | Prompt ID | `prompt_id` | NUMBER | High cardinality, so it reads well in a table but poorly as a breakdown. | > | 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. | > | 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. | > | 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 | Total AI responses collected. 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 (Percent) (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 (Percent) (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. | > [!NOTE] > > Date dimensions cover the **last 90 days** only. For weekly charts, keep date filters week-aligned. > [!TIP] > > To approximate Scrunch's **Competitive Benchmark** view, pair `Competitor Name` with `Competitor Mention Share of Voice (%)`, or chart `Brand Mention Share of Voice (%)` against it. A single field that reproduces the visualization exactly still doesn't exist, but share of voice gets close. ## Using the Scrunch Looker Studio Template To accelerate setup and reporting, Scrunch provides a pre-built template. **1. Open the template** Click the template link. > [card] [Scrunch Looker Studio Template](https://lookerstudio.google.com/reporting/c16759f5-d47e-49a0-a43a-9211b721c300) **2. Make a copy** In the top-right corner, click the **three dots** → **Make a copy**. > [!NOTE] > > Be sure to install the [Scrunch Looker Studio Connector](https://lookerstudio.google.com/datasources/create?connectorId=AKfycbzRRK2rRqh1_ujHS313hitMb5PopzgNUS5m5ih6ohI) prior to copying. ![Copy Pn](https://mintcdn.com/scrunchai/67YuQjB0mGKJxVaT/images/copy.png?fit=max\&auto=format\&n=67YuQjB0mGKJxVaT\&q=85\&s=19b1ebd95e3912331f0dc9c5d4601048) **3. Connect your Scrunch data source** When prompted, select the Scrunch AI Looker Studio connector you configured earlier. ![Data Pn](https://mintcdn.com/scrunchai/67YuQjB0mGKJxVaT/images/data.png?fit=max\&auto=format\&n=67YuQjB0mGKJxVaT\&q=85\&s=a708648d040a50b094756a9d4aab4508) **4. Customize your dashboard** You can now modify charts, add filters, or blend additional sources like GA4, CRM data, paid media, and more. ## FAQs **How do I compare last week vs. previous week?** > Create custom metrics inside Looker Studio using conditional date filters. Example: > > * Last 7 days > * Same 7 days previous period > * Month-to-date vs prior month-to-date > > Looker Studio supports calculated fields using functions like: > > ```text theme={null} > CASE > WHEN DATE_DIFF(CURRENT_DATE(), date, DAY) < 7 THEN brand_presence_percentage > END > ``` **Are there limits to dashboard size?** > Yes. Looker Studio allows a maximum of 30 concurrent Community Connector queries. Dashboards with more than \~15 Scrunch-powered charts may hit this limit depending on complexity. **How do I recreate the Brand Presence + Competitor Presence chart from the Scrunch dashboard?** > A version of this combined view is already included in the Scrunch Looker Studio template. When you make a copy of the template, zoom out on the canvas—you'll see a hidden chart that mimics the dual-line Brand vs. Competitor Presence visualization from the Scrunch dashboard. > > Looker Studio does not natively blend these metrics into a single field, so the chart requires custom-calculated metrics under the hood. Each competitor's presence must be defined using a conditional formula, such as: > > ```text theme={null} > CASE WHEN competitor_name = "Competitor A" THEN competitor_presence_percentage END > ``` > > **To customize the benchmark view for your own competitive set:** > > 1. Open the hidden chart in your copied template > 2. Edit each metric formula > 3. Replace the competitor names with the ones relevant to your brand > > > [!NOTE] > > > > There is no universal "competitive benchmark" metric available from the API. The Looker Studio template replicates this view by combining multiple calculated fields inside one chart. > > ![Alt Chart Pn](https://mintcdn.com/scrunchai/67YuQjB0mGKJxVaT/images/alt-chart.png?fit=max\&auto=format\&n=67YuQjB0mGKJxVaT\&q=85\&s=d85796133f4e3e78f2dc1017a0fd0700) ## Resetting Your Connector (If Needed) If the connector was set up incorrectly, here's how to completely reset it: **1. Open Looker Studio Admin** Visit: [https://lookerstudio.google.com/navigation/reporting](https://lookerstudio.google.com/navigation/reporting) **2. Open Data Sources** Click Data Sources in the top navigation. **3. Remove the Scrunch data source** Find your Scrunch connector → ⋮ → Remove ![Data Source Pn](https://mintcdn.com/scrunchai/67YuQjB0mGKJxVaT/images/data-source.png?fit=max\&auto=format\&n=67YuQjB0mGKJxVaT\&q=85\&s=9a015d42e3b561c5a976d789bf838ea4) > [!TIP] > > This could be named "**AI Data Connector**." **4. Now remove the connector** Click + Create → Data source → Partner Connectors → Scrunch AI. Then ⋮ → Revoke ![Delete Pn](https://mintcdn.com/scrunchai/67YuQjB0mGKJxVaT/images/delete.png?fit=max\&auto=format\&n=67YuQjB0mGKJxVaT\&q=85\&s=bd74b7960778ca4ed8f48adb9722b882) **5. Reinstall the connector** Use the connector link again: [https://lookerstudio.google.com/datasources/create?connectorId=AKfycbzRRK2rRqh1_ujHS313hitMb5PopzgNUS5m5ih6ohI](https://lookerstudio.google.com/datasources/create?connectorId=AKfycbzRRK2rRqh1_ujHS313hitMb5PopzgNUS5m5ih6ohI) **6. Re-enter your API key and brand ID** You now have a clean state. ## Summary > [card] Flexible Reporting > > Build dashboards for brand trends, sentiment, competitors, and platform performance. > [card] Blend with GA4 > > Unify Scrunch visibility metrics with site traffic and conversion data. > [card] Template-Ready > > Use our prebuilt Looker Studio template to jumpstart reporting. # Meet Scrunchie Source: https://developers.scrunch.com/mcp/overview Connect your Scrunch data to Claude, ChatGPT, and other AI assistants. Ask questions in plain English and get answers from your live data. ![Scrunch MCP banner](https://mintcdn.com/scrunchai/Xn4EEeBaa2q1GkTh/images/ChatGPT-Image-May-14,-2026,-09_14_42-AM.png?fit=max\&auto=format\&n=Xn4EEeBaa2q1GkTh\&q=85\&s=df235994b3ea4eabecd3c70841abd1fd) The Scrunch MCP lets you query your brand monitoring data directly inside Claude, ChatGPT, Microsoft Copilot, and other AI assistants - no API key, no code, no dashboard switching. You authenticate once with your Scrunch account, and from then on your assistant can answer questions like "How has our presence trended this quarter?" or "Which competitors are winning on Perplexity?" using your live data. *** ## What you can do > [card] Read metrics and responses > > Filter and pull your Scrunch data like presence, position, sentiment, and citations across AI platforms. > [card] Manage configuration > > Create and update brands, competitors, personas, and prompts all in one natural language conversation. > [card] Agent Traffic > > Import AI agent crawl logs from a CSV and query which AI crawlers are hitting your site, how often, and on which pages. > [card] [Switching from another tool?](/mcp/workflows/switch-from-another-tool) > > Migrate your brands, prompts, personas, tags, alternative names, and competitors into Scrunch with one export prompt and one import prompt. Works whether your current tool has an MCP, CSV export, or just a settings page you can copy from. *** ## How it works **1. Connect once** Add the Scrunch MCP server to your AI client of choice. Your assistant redirects you to Scrunch's normal sign-in flow — no shared secrets or API keys to manage. [See the setup guide →](/mcp/setup) **2. Ask in plain English** Start a conversation and ask about your brand. Your assistant automatically selects the right Scrunch features, resolves your brand ID, and anchors date ranges like "last 30 days" to today's date before querying. **3. Get live answers** Responses are grounded in your actual Scrunch data — your brands, your competitors, your prompts, your metrics. You can ask follow-up questions, request comparisons, and have the assistant draft summaries or slide copy based on what it finds. *** ## What you need > [!NOTE] > > **Prerequisites** > > * A Scrunch account (any plan). Your existing brand permissions carry over automatically. > * A compatible AI client: Claude (Free, Pro, Max, Team, or Enterprise), ChatGPT (Plus, Pro, Team, Enterprise, or Edu — Developer Mode required), ChatGPT Dots, Perplexity, Grok, Grok Bot, Microsoft Copilot Studio, Cursor, VS Code, Codex, Muse, Devin, or any other client that supports remote MCP servers. > * About 5 minutes to complete the setup. *** ## Known limitations > [!WARNING] > > Most of what's in the Scrunch dashboard is available through MCP, but a few things aren't accessible yet: > > 1. **Cited pages and URL detail** — Aggregate citation metrics show the overall split between brand-owned, competitor, and third-party sources, but not which specific URLs are being cited. Individual citation URLs are available on raw responses via the `list_responses` feature. > 2. **Sitemap and Page Audit data** — Not currently available via MCP. It will be available in a future update. > 3. **Accounts with many prompts** — Results are capped at 1,000 records per request. If you manage a large number of prompts, filter by tag or date range to stay within this limit. *** ## Get started > [card] [Setup guide](/mcp/setup) > > Connect the Scrunch MCP to Claude, ChatGPT, Grok, and other AI tools. Takes about 5 minutes. > [card] [Workflows](/mcp/workflows/weekly-ai-brief) > > Multi-tool workflows that combine Scrunch with Notion, Slack, and other AI apps — copy-paste ready. > [card] [Prompt Library](/mcp/prompts/visibility-overview) > > 35+ ready-to-copy prompts for visibility analysis, competitive intelligence, reporting, and configuration. > [card] [Feature Reference](/mcp/tools) > > Everything available via MCP, with descriptions and example prompts. # Citation Analysis Source: https://developers.scrunch.com/mcp/prompts/citation-analysis Find which pages AI is citing from your site, which topic areas get skipped, and which third-party sources are driving your mentions. Citations tell you what AI is actually reading to talk about \[brand name]. These prompts show you which owned pages are working, which aren't being used despite being relevant, and which third-party sources have the most influence. *** > [accordion] See Which Pages AI Is Citing From Your Site > > How often is AI citing \[brand name]'s own content — and which topic areas have zero citations? > > ```text theme={null} > For [brand name], pull prompt variants filtered to citation_domain = [brand domain] (e.g., "brandname.com"). > > Report: > 1. How many variants cite [brand domain]? > 2. What percentage of total tracked variants does this represent? > 3. What tags and topics are the cited variants concentrated in? > 4. Are there tags with zero or near-zero citations from [brand domain]? Those are content citation gaps. > ``` > [accordion] Find Topics Where AI Skips Your Content > > Topic areas where AI is answering questions but not pulling from \[brand name]'s pages — even when those pages exist. > > ```text theme={null} > For [brand name], run a citation coverage analysis. For each major tag in the brand's configuration: > 1. Pull variants with that tag where citation_domain = [brand domain] — count > 2. Pull total variants with that tag — count > 3. Calculate citation rate per tag > > Rank tags by citation rate from lowest to highest. Tags with low citation rates despite having tracked prompts are content gaps — AI is answering these questions but not citing [brand name]'s content. > ``` > [accordion] See Which Competitor Pages AI Cites Most > > Which competitor domains is AI pulling from — and on which topics are they getting cited instead of \[brand name]? > > ```text theme={null} > For [brand name], I want to see which competitor domains are being cited in AI responses. Run pulls filtered to citation_domain for each main competitor's domain: > - citation_domain = [competitor1.com] > - citation_domain = [competitor2.com] > - citation_domain = [competitor3.com] > > For each, report the count and which tags/topics they're concentrated in. Which competitor's content is AI pulling from most? On which topics is their content being cited instead of [brand name]'s? > ``` > [accordion] Identify Third-Party Sites Driving Your AI Mentions > > When \[brand name] appears in AI responses via third-party sources, which sites are responsible? These are the highest-leverage PR and partnership targets. > > ```text theme={null} > For [brand name], pull variants where: > - brand_present = true > - citation_domain is NOT [brand domain] (i.e., [brand name] is mentioned but via third-party sources) > > Limit to 30 results. What third-party domains are responsible for [brand name]'s AI mentions? Are there publications, directories, or review sites that AI consistently uses to reference [brand name]? These are the highest-leverage third-party PR and link targets. > ``` *** > [card] [White Space & Growth Opportunities](/mcp/prompts/white-space) > > Find the topic areas where neither \[brand name] nor competitors are showing up yet. > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Full workflow: gap analysis into a Notion tracker with content recommendations. # Competitive Intelligence Source: https://developers.scrunch.com/mcp/prompts/competitive-intel MCP prompts to rank competitors by AI share of voice, identify where rivals are displacing your brand, and surface positions you need to protect in AI search. These prompts compare \[brand name] against every tracked competitor — from a full share of voice ranking to a detailed head-to-head on the specific prompts you're losing. *** > [accordion] Rank Competitors by Share of Voice > > Which competitors appear most often across \[brand name]'s tracked prompts — and how dominant are they? > > ```text theme={null} > For [brand name], first list all configured competitors to get their IDs. Then for each competitor, pull the count of variants where competitor_present = [competitor ID]. > > Build a competitor presence ranking: which competitors appear most frequently in AI responses across [brand name]'s tracked prompts? Calculate each competitor's presence rate vs. total variants. Rank them. Flag any competitor appearing in more than 30% of prompts — that's a dominant player worth analyzing further. > ``` > [accordion] See Where a Competitor Is Beating You > > The specific prompts where \[competitor name] shows up and \[brand name] doesn't — direct displacement, ranked by observation count. > > ```text theme={null} > For [brand name], get the competitor ID for [competitor name] from the competitors list. Then pull variants filtered to: > - competitor_present = [competitor ID] > - brand_present = false > > Limit to 50 results. This shows prompts where [competitor name] appears in AI responses but [brand name] does not. > > For this set: > 1. What topics or categories are these? Tag/topic breakdown > 2. Are these branded or unbranded queries? > 3. What is [competitor name] likely doing well that [brand name] isn't for these queries? > 4. Which of these represent the most valuable queries to reclaim — highest observation count, most commercially relevant topics? > ``` > [accordion] Build a Full Competitive Displacement Map > > For every competitor: how many prompts do they win outright vs. share with \[brand name]? > > ```text theme={null} > For [brand name], list all competitors and get their IDs. For each competitor, run two counts: > 1. competitor_present = true, brand_present = false → competitor wins, brand loses > 2. competitor_present = true, brand_present = true → both appear (co-mentions) > > Build a displacement table showing for each competitor: how many prompts they win outright vs. share. Rank competitors by displacement rate. The top competitors are actively taking visibility that [brand name] should own. > ``` > [accordion] Find Your Defensible Positions > > The prompts where \[brand name] appears and top competitors don't — the territory to protect and expand. > > ```text theme={null} > For [brand name], pull variants where brand_present = true. Within this set, identify which prompts are non-branded (branded = false) — these are category queries where [brand name] is earning unprompted AI visibility. > > Separately, for the top 3 competitors by presence rate, check their presence on the same prompts using competitor_present filter. Identify prompts where [brand name] appears and those competitors do not — these are [brand name]'s defensible positions. > ``` *** > [card] [Competitor Share of Voice, Ranked](/mcp/workflows/competitor-share-of-voice) > > Full workflow: complete SOV ranking with displacement map and optional Slack post. > [card] [Citation Analysis](/mcp/prompts/citation-analysis) > > See which competitor pages AI is citing — and which of yours aren't getting cited. # Configuration & Maintenance Source: https://developers.scrunch.com/mcp/prompts/configuration Audit your Scrunch setup, find duplicate prompts, check platform coverage, standardize tags, and clean up stale configuration with conversational MCP prompts. A clean configuration produces accurate data. Use these prompts to audit your setup before a reporting cycle, clean up stale or duplicate prompts, and ensure your tag structure stays consistent as brands and teams grow. *** > [accordion] Full Configuration Audit > > Are the right competitors, tags, and prompts in place? Flag gaps that would skew your visibility data. > > ```text theme={null} > For [brand name], run a full configuration audit: > 1. List all competitors — are any major players missing from the industry? > 2. Get all tags — do the tags represent the full scope of how buyers research this category? > 3. Pull total variant count — are there enough prompts to generate statistically meaningful data? > 4. Pull branded = true variant count — do branded queries make up a reasonable share of tracking? > 5. Pull branded = false variant count — are enough unbranded category queries being tracked? > > Flag any gaps in configuration that would skew the visibility data. > ``` > [accordion] Find and Remove Duplicate Prompts > > Identify near-duplicate prompts within a tag group before they inflate counts and distort visibility rates. > > ```text theme={null} > For [brand name], pull all seed prompts tagged as [tag name]. Review the prompt text for duplicates, near-duplicates, or prompts so similar they're tracking the same query twice. List candidates for archiving. Do not archive anything without my confirmation. > ``` > [accordion] Check Platform Coverage Gaps > > Are any prompts running on some platforms but not others when they should be everywhere? > > ```text theme={null} > For [brand name], pull seed prompts and their variant_scenarios field. Identify any seed prompts that are not running on all platforms (e.g., running on ChatGPT and Perplexity but not Gemini or Grok). List these coverage gaps by seed prompt. Flag whether the missing platform coverage appears intentional or like an oversight. > ``` > [accordion] Standardize Your Tag Structure > > Find orphaned tags, overlapping names, and uncategorized prompts — then get a recommended structure. > > ```text theme={null} > Get all tags for [brand name]. Identify: > 1. Tags with fewer than 5 prompts — likely orphans or misfiled > 2. Tags whose names overlap in meaning (e.g., "competitors" vs. "alternatives" vs. "compare") > 3. Tags with no clear category alignment > > Suggest a consolidated tag structure. Then, for any tag with fewer than 5 prompts, list those prompts so I can decide whether to reassign them. > ``` > [accordion] First-Week Baseline > > Establish a Day 1 reading for a brand that just went live, to compare every future report against. > > ```text theme={null} > For [brand name], establish a baseline reading now that the brand just went live in Scrunch. > > 1. Pull total variant count and confirm data has started collecting (variants should show non-zero observation counts within 24-48 hours of setup) > 2. Get presence, position, and sentiment metrics for the data collected so far > 3. List all tags and confirm prompts are distributed across them as expected > > Present this as a "Day 1" baseline I can compare all future reports against. Flag anything that looks like it isn't collecting data yet. > ``` > [accordion] Prompt Coverage Audit > > Platform coverage isn't the only gap worth checking — confirm prompts span the full buying journey too. > > ```text theme={null} > For [brand name], check whether our tracked prompts actually cover the full buying journey, not just one stage. > > 1. Get all tags and identify which represent funnel stages (awareness, consideration, decision) versus topic/product tags > 2. Pull variant counts for each funnel-stage tag > 3. Flag if any stage is significantly under-tracked relative to the others (e.g., dozens of awareness-stage prompts but almost no decision-stage prompts) > > Recommend which funnel stage most needs new prompts added, and roughly how many. > ``` *** > [card] [New Brand Live in One Conversation](/mcp/workflows/new-brand-live) > > Starting from scratch? Configure a brand, competitors, and prompts in a single chat. > [card] [Feature Reference](/mcp/tools) > > See everything available via MCP with descriptions and example prompts. # Platform-Specific Analysis Source: https://developers.scrunch.com/mcp/prompts/platform-analysis MCP prompts that compare brand visibility on ChatGPT, Perplexity, Gemini, and Google AI Overviews to find which platform is underperforming and why. ChatGPT, Perplexity, Gemini, and Google AI Overviews don't behave the same way. Use these prompts to find where \[brand name] underperforms on specific platforms and what's different about the queries it's losing there. *** > [accordion] Diagnose Your Weakest AI Platform > > Visibility rates ranked by platform — plus the specific prompts driving the worst performance. > > ```text theme={null} > For [brand name], run the following analysis for each major platform (chatgpt, perplexity, claude, gemini, grok, meta): > - Total variants on that platform > - brand_present = true count on that platform > - brand_present = false count on that platform > - Visibility rate per platform > > Rank platforms by visibility rate. For the two lowest-performing platforms, pull 10 example prompts where brand_present = false to show what types of queries [brand name] is missing there. > ``` > [accordion] Deep-Dive a Specific Platform's Gaps > > What is \[brand name] consistently missing on one particular platform? Are the gaps topic-specific? > > ```text theme={null} > For [brand name], pull prompt variants filtered to: > - platform = [platform name] > - brand_present = false > > Limit to 30 results sorted by observation_count descending. What is [brand name] consistently missing on [platform name]? Are the gaps concentrated in specific topics or tags? Is there a pattern to what [platform name] tends to surface vs. what [brand name] provides? > ``` > [accordion] Find Platform Inconsistencies > > Prompts where \[brand name] appears on ChatGPT but not Perplexity (or vice versa) — these inconsistencies reveal platform-specific optimization opportunities. > > ```text theme={null} > For [brand name], I want to find prompts where [brand name] appears on some platforms but not others. > > Pull variants where brand_present = true for platform = chatgpt. Then pull brand_present = false for the same tag set on platform = perplexity. Compare the overlap — identify seed prompts where ChatGPT cites [brand name] but Perplexity doesn't (or vice versa). These inconsistencies reveal platform-specific optimization opportunities. > ``` *** > [card] [Visibility Overview](/mcp/prompts/visibility-overview) > > Get the full cross-platform visibility picture before drilling into a specific platform. > [card] [Citation Analysis](/mcp/prompts/citation-analysis) > > See which content is being cited on each platform and where the gaps are. # Rankings & Priority Lists Source: https://developers.scrunch.com/mcp/prompts/rankings MCP prompts that return ranked top-10 and bottom-10 lists of best performing prompts, biggest missed opportunities, and weakest topic areas for triage. These prompts produce ranked lists optimized for two jobs: sharing the wins with stakeholders and triaging where to act next. Each one returns a top-10 or bottom-10 view sorted by observation count or visibility rate. *** > [accordion] See Your Top 10 Performing Prompts > > The highest-visibility prompts — what's driving them, and what do they have in common? > > ```text theme={null} > For [brand name], pull prompt variants filtered to brand_present = true. Sort by observation_count descending. Return the top 10. > > For each: > - Show the seed prompt text > - Show the platform > - Show the observation count > - Note whether it's branded or unbranded > - Note the tag/topic > > Summarize: what do [brand name]'s best-performing prompts have in common? Topic, framing, funnel stage? > ``` > [accordion] Find Your 10 Biggest Missed Opportunities > > The most-observed queries where \[brand name] is absent — ranked by how much it matters. > > ```text theme={null} > For [brand name], pull prompt variants filtered to brand_present = false. Sort by observation_count descending. Return the top 10. > > For each: > - Show the seed prompt text > - Show the platform > - Show the observation count > - Note whether it's branded or unbranded > - Note which competitors appear instead (if any) > > Prioritize: which of these 10 gaps represents the most urgent fix, and why? > ``` > [accordion] Find Where a Competitor Most Displaces You > > The highest-observation prompts where \[competitor name] appears and \[brand name] doesn't — what to fix first. > > ```text theme={null} > For [brand name], get the competitor ID for [competitor name]. Pull variants filtered to: > - competitor_present = [competitor ID] > - brand_present = false > > Sort by observation_count descending. Return top 10. > > These are the highest-stakes losses — prompts where [competitor name] is getting the AI mention and [brand name] isn't. For each, identify what content [brand name] would need to create or optimize to compete. > ``` > [accordion] Find Your Most-Cited Pages > > The owned pages that AI cites most often — understand what makes them work so you can replicate it. > > ```text theme={null} > For [brand name], pull variants filtered to citation_domain = [brand domain]. Sort by observation_count descending. Return top 10. > > These are the prompts where [brand name]'s own content is getting cited most by AI. Note which pages are cited and what topics they cover. These are the pages to protect, expand, and use as a model for other content. > ``` > [accordion] Rank Your Weakest Topic Areas > > Tag groups with the lowest visibility rate — combining gap size and observation volume into a single priority score. > > ```text theme={null} > For [brand name], get all tags. For each tag, pull: > - Total variant count for that tag > - brand_present = true count for that tag > > Calculate visibility rate per tag. Return the 10 tags with the lowest visibility rate. Rank by urgency: low visibility rate combined with high observation count = highest priority. > ``` *** > [card] [Reporting Digests](/mcp/prompts/reporting) > > Package these rankings into a pre-call brief, monthly digest, or QBR summary. > [card] [Monthly Client Report](/mcp/workflows/monthly-client-report) > > Full workflow: pull all the data and have Claude write and save the complete report. # Reporting Digests Source: https://developers.scrunch.com/mcp/prompts/reporting MCP prompts that generate structured monthly digests, QBR slides, client call prep docs, and onboarding briefs ready to drop into a presentation. These prompts produce complete, structured reports — not raw data. Each one is designed to go directly into a client presentation, stakeholder update, or call prep doc with minimal editing. *** > [accordion] Monthly Visibility Digest > > A complete month-in-review, structured for sharing with clients or leadership. > > ```text theme={null} > For [brand name], build a monthly AI visibility digest. > > Pull: > 1. Total tracked variants — count > 2. brand_present = true — count → calculate overall visibility rate > 3. brand_present = true by platform — count per platform > 4. brand_present = false sorted by observation_count, top 10 — the month's biggest gaps > 5. Competitor presence counts for top 3 competitors > 6. Tags with lowest visibility rate — top 5 gap tags > > Organize into this structure: > - Visibility Score: [X]% overall, with platform breakdown > - Top Performing Areas: where brand presence is strongest > - Priority Gaps: top 10 missing prompts by observation volume > - Competitive Snapshot: competitor presence rates > - Recommended Actions: 3 specific items for the next 30 days > ``` > [accordion] New Client Baseline Report > > The starting-point snapshot for a new brand — configuration health, current visibility, and first priorities. > > ```text theme={null} > I'm establishing a baseline for [brand name] in Scrunch. Run the following: > > 1. List all competitors — count and names > 2. Get all tags — count and names > 3. Total tracked variants — count > 4. brand_present = true — count → overall visibility rate > 5. branded = true, brand_present = false — count → branded query gaps (should be near zero) > 6. brand_present = false, top 5 by observation_count — the most critical current gaps > > Deliver as a baseline report with: > - Configuration Health: are the right competitors and tags set up? > - Current Visibility Rate: overall and by platform > - Immediate Gaps: branded queries where [brand name] isn't appearing > - Top 5 Priorities for the first 90 days > ``` > [accordion] Pre-Call Brief in 60 Seconds > > Five talking points before a client or stakeholder call — just the numbers that matter, nothing else. > > ```text theme={null} > I have a call with [brand name] in [X] minutes. Give me a quick brief. > > Pull: > 1. Overall visibility rate (brand_present = true / total) > 2. Best platform and worst platform by visibility rate > 3. Top 3 prompts by observation count where brand_present = false — the headline gaps > 4. Any branded queries where brand_present = false — urgent issues to flag > > Give me 5 key talking points I can use in the call. One sentence each, lead with the number. Keep it tight — I need something I can scan in 2 minutes. > ``` > [accordion] Quarterly Business Review Summary > > Full QBR structure: performance, competitive position, content gaps, and next quarter's focus. > > ```text theme={null} > For [brand name], build a quarterly business review summary for AI visibility. > > Pull and analyze: > 1. Overall visibility rate vs. benchmark (brand_present=true rate vs. total) > 2. Platform breakdown — visibility rate per LLM > 3. Top 5 tags by visibility rate (strengths) > 4. Bottom 5 tags by visibility rate (gaps) > 5. Competitive displacement — for each tracked competitor, how many prompts do they appear in where [brand name] does not? > 6. Top 3 citation domains (brand's own domain + top 2 competitor domains) > > Structure as: Performance Summary → Competitive Position → Content Gaps → Recommended Next Quarter Focus > ``` *** > [card] [Monthly Client Report, Built Automatically](/mcp/workflows/monthly-client-report) > > Full workflow: Claude pulls all the data, writes the report, and saves it to Notion. > [card] [Weekly AI Brief → Notion & Slack](/mcp/workflows/weekly-ai-brief) > > Keep stakeholders updated between monthly reports with an automated weekly brief. # Sentiment Signals Source: https://developers.scrunch.com/mcp/prompts/sentiment-signals MCP prompts that go beyond the presence question to check how AI assistants actually talk about your brand — positive, mixed, or negative — and why. Being mentioned isn't the same as being spoken about well. These prompts focus specifically on `get_sentiment_metrics` and the response text behind it, to answer not just "are we present" but "how are we described when we are." *** > [accordion] Get a Sentiment Snapshot > > A quick read on how AI assistants currently talk about the brand, and whether that's shifting. > > ```text theme={null} > For [brand name], get sentiment metrics for the last 30 days, and again for the 30 days before that. > > Show the positive/mixed/negative split for both periods and the change. Break it down by AI platform — is sentiment consistent across ChatGPT, Perplexity, Gemini, and Google AI Overviews, or is one platform notably more critical? > > Summarize in one sentence: is sentiment improving, holding steady, or declining? > ``` > [accordion] Compare Sentiment Against a Competitor > > Not just "are we positive" — positive relative to who. > > ```text theme={null} > For [brand name], get sentiment metrics for the last 30 days for [brand name] and [competitor name] side by side. > > Compare the positive/mixed/negative split for both brands. If one brand is described more favorably, pull 2-3 example prompts that illustrate the gap. > ``` > [accordion] Drill Into a Negative Sentiment Read > > Don't just see the negative percentage — read what's actually being said. > > ```text theme={null} > For [brand name], get sentiment metrics for the last 30 days filtered to negative sentiment only. List the specific prompts and platforms where this occurred. > > For the 3 highest-observation prompts, pull the full response text with get_response. What specific claim, comparison, or complaint is driving the negative read? Is it the same issue repeating across responses, or several unrelated ones? > ``` *** > [card] [Brand Presence & Visibility](/mcp/prompts/visibility-overview) > > Pair sentiment with the presence numbers for the fuller picture of how the brand shows up. > [card] [Competitive Intelligence](/mcp/prompts/competitive-intel) > > Extend the sentiment comparison prompt to your full tracked competitor set. # Trends & Alerts Source: https://developers.scrunch.com/mcp/prompts/trends-and-alerts MCP prompts that frame metrics over time — what changed since last period, what's been quietly sliding, and what's crossed a threshold worth flagging. A single snapshot can hide a slow decline or overstate a one-off spike. These prompts are built around comparison — this period against last, or against a threshold you set — so movement gets caught early instead of showing up as a surprise in the monthly report. *** > [accordion] See What Changed Since Last Month > > A fast before/after read across every core metric. > > ```text theme={null} > For [brand name], compare the last 30 days against the 30 days before that for presence, position, sentiment, and citation metrics. > > For each metric, show the change and call out which one moved the most — in either direction. Give me a one-paragraph summary of the month's biggest story. > ``` > [accordion] Catch a Slow Decline Before It's a Crisis > > A single bad month can be noise. Three in a row is a trend. > > ```text theme={null} > For [brand name], get presence metrics for each of the last 3 months separately (not combined). > > Identify any tag or platform where presence has declined in each of the 3 consecutive months, even if each individual drop looks small. A steady 3-month decline is worth flagging even if no single month looks alarming on its own. > ``` > [accordion] Flag Anything Past a Threshold > > Skip the full review — just tell me if something crossed a line. > > ```text theme={null} > For [brand name], check whether any of the following happened in the last 7 days: > - Presence rate dropped more than [5] percentage points vs. the prior 7 days > - Sentiment (positive share) dropped more than [5] percentage points > - Any tracked competitor's share of voice increased more than [10] percentage points > - Citation share to [brand domain] dropped more than [5] percentage points > > If nothing crossed a threshold, just say so in one line. If something did, tell me exactly what and by how much — no other commentary needed. > ``` *** > [card] [Weekly Visibility Alert to Slack](/mcp/workflows/weekly-visibility-alert-slack) > > Automate the threshold-check prompt above into a recurring Slack post. > [card] [Reporting Digests](/mcp/prompts/reporting) > > Roll a monthly trend read into a structured digest for stakeholders. # Visibility Gaps & Content Opportunities Source: https://developers.scrunch.com/mcp/prompts/visibility-gaps MCP prompts that find topics where your brand is absent from AI responses, rank gaps by urgency, and group them into actionable content opportunities. These prompts surface where \[brand name] isn't showing up and help you understand why. Use them before a content planning session or when you need to identify where to invest next. *** > [accordion] Find Your Biggest Content Gaps by Topic > > Which topic areas have the worst visibility? Ranked by gap rate so you know where to invest first. > > ```text theme={null} > For [brand name], get all tags from the Scrunch configuration. For each tag, pull: > - Total variants with that tag > - Variants with that tag where brand_present = false > > Calculate a "gap rate" per tag (brand absent / total). Rank tags by gap rate from highest to lowest. The top tags are the highest-priority content investment areas. Show me the top 10 gap tags and list 5 example prompts from each of the top 3. > ``` > [accordion] Map the Category Queries You're Missing > > Unbranded, category-level queries where \[brand name] is invisible — clustered into actionable themes. > > ```text theme={null} > For [brand name], pull prompt variants filtered to: > - branded = false (unbranded category or comparison queries) > - brand_present = false > > Limit to 50 results sorted by observation_count descending. > > For this set: > 1. What topics or categories are these prompts in? > 2. What does a prospect appear to be searching for when [brand name] doesn't appear? > 3. Group these into 3–5 thematic clusters — these represent distinct content gap areas > 4. For each cluster, identify what type of content [brand name] would need to appear for these queries > ``` > [accordion] Surface Your Highest-Priority Missed Prompts > > The most-observed queries where \[brand name] isn't showing up — ranked by urgency. > > ```text theme={null} > For [brand name], pull prompt variants where brand_present = false. Sort by observation_count descending. Return the top 25. > > For each: > - Show the prompt text > - Show the platform > - Show the observation count > - Note whether it's a branded or unbranded query > > Flag any branded queries in this list — a brand missing its own branded queries at high observation volume is an urgent issue. > ``` > [accordion] Find Near-Miss Prompts (Easy Wins) > > Category queries where \[brand name] is close to appearing — the fastest visibility gains available right now. > > ```text theme={null} > For [brand name], I want to identify prompts where [brand name] is close to appearing but isn't yet. > > Pull prompt variants where: > - brand_present = false > - branded = false > - The prompt text contains keywords related to [brand name]'s core category (use search filter: "[category keyword]") > > List up to 30 results. For each, explain why [brand name] likely doesn't appear and what content change would most likely flip this to a brand_present = true result. > ``` *** > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Full workflow: gap analysis → prioritized Notion tracker with content recommendations. > [card] [Competitive Intelligence](/mcp/prompts/competitive-intel) > > Check whether competitors are winning the gaps you just found. # Brand Presence & Visibility Source: https://developers.scrunch.com/mcp/prompts/visibility-overview Starter MCP prompts that calculate your AI visibility score and establish where your brand stands across tracked prompts, platforms, and reporting cycles. Start here. These four prompts give you a complete picture of \[brand name]'s visibility across all tracked prompts and platforms before you dig into gaps or competitive analysis. Replace `[brand name]` with the brand you're analyzing and paste directly into Claude with Scrunch connected. *** > [accordion] Calculate Your AI Visibility Score > > Overall visibility rate across all tracked prompts and platforms, ranked by AI model. > > ```text theme={null} > For [brand name] in Scrunch, calculate the brand's overall AI visibility rate. > > 1. Pull the total number of prompt variants tracked for [brand name] — count only > 2. Pull the count of variants where brand_present = true — count only > 3. Calculate the visibility rate: (brand present / total) × 100 > 4. Break this down by platform — run the same brand_present=true count filtered to each LLM (ChatGPT, Perplexity, Claude, Gemini, Grok, Meta) > 5. Rank platforms from highest to lowest visibility rate > > Present the overall rate, the platform breakdown, and flag any platform where [brand name] is significantly above or below its average. > ``` > [accordion] See Exactly Where You're Winning > > Which queries and topics is \[brand name] already appearing in? What patterns explain those wins? > > ```text theme={null} > For [brand name], pull prompt variants filtered to brand_present = true. Limit to 50 results. > > For this set, tell me: > 1. Which platforms have the most brand presence > 2. Which tags or topic categories appear most frequently — what topics does [brand name] win on? > 3. Are these primarily branded queries (someone asking directly about [brand name]) or unbranded category queries? > 4. What does the brand appear to be doing well based on the types of prompts where it appears? > ``` > [accordion] Check Branded Query Coverage > > Is \[brand name] showing up every time someone asks an AI about it directly? It should be — flag if not. > > ```text theme={null} > For [brand name], pull prompt variants filtered to: > - branded = true (queries specifically asking about [brand name]) > - brand_present = false > > Count how many branded queries exist where [brand name] is NOT appearing in AI responses. This should be zero or near-zero for a healthy brand — flag if it's significant. List up to 20 of these prompts so I can see which branded queries the brand is missing. > ``` > [accordion] Compare Visibility Across AI Platforms > > Side-by-side visibility rates for every platform — which are strong, which are priority gaps? > > ```text theme={null} > For [brand name], run the following and report counts for each: > 1. Total prompt variants (no filter) > 2. brand_present = true, platform = chatgpt > 3. brand_present = true, platform = perplexity > 4. brand_present = true, platform = claude > 5. brand_present = true, platform = gemini > 6. brand_present = true, platform = grok > 7. brand_present = true, platform = meta > > For each platform, calculate the visibility rate vs. total variants on that platform. Rank platforms. Flag any where visibility is under 20% — those are priority gaps. > ``` > [accordion] Read the Actual Answers > > Don't just trust the aggregate rate — read how the brand is actually being described. > > ```text theme={null} > For [brand name], pull the actual response text behind the numbers instead of just the aggregate rate. > > 1. Pull prompt variants filtered to brand_present = true. Take the 5 highest-observation results. > 2. For each, fetch the full response with get_response — the raw text, not just the presence flag. > 3. Read how [brand name] is actually described: is it a recommendation, a passing mention, or one option among many? > > Summarize: does the way [brand name] is described match how the brand wants to be positioned, or is the framing off even when presence is technically counted as a win? > ``` *** > [card] [Visibility Gaps & Content Opportunities](/mcp/prompts/visibility-gaps) > > Find where the brand is absent and which gaps are most urgent to address. > [card] [Weekly AI Brief → Notion & Slack](/mcp/workflows/weekly-ai-brief) > > Use these numbers in an automated weekly brief saved to Notion and posted to Slack. # Visualize It Source: https://developers.scrunch.com/mcp/prompts/visualize-it MCP prompts that turn a metric question directly into a Scrunch Explorer chart or saved dashboard, using generate_explorer_chart and create_explorer_dashboard. Sometimes a number needs a picture. These prompts use Scrunch's Explorer tools to turn any metric question into an interactive chart or a saved multi-tile dashboard, each returning a link you can revisit or share. *** > [accordion] Chart Any Metric Question > > Turn a plain-English question directly into a chart instead of a table of numbers. > > ```text theme={null} > For [brand name], chart [metric — e.g. presence, position, sentiment, or citations] over the last [30/90] days, broken down by [platform / competitor / tag — whichever applies]. > > Give me the link to the chart, and tell me in one sentence what it shows. > ``` > [accordion] Build a Standing Dashboard > > Assemble several metrics into one saved view instead of asking for them one at a time. > > ```text theme={null} > For [brand name], build an Explorer dashboard with tiles for: overall presence rate, sentiment breakdown, citation ownership split, and share of voice vs. our top 3 competitors. > > Mix a couple of headline "card" tiles with line or bar charts for the trend-based ones. Give me the dashboard link when it's ready. > ``` > [accordion] Put Two Brands on One Chart > > Compare directly instead of eyeballing two separate numbers. > > ```text theme={null} > For [brand name], chart presence rate over the last 90 days with [competitor name] overlaid on the same chart for direct comparison. > > Tell me the link, and call out any point in the period where the two lines crossed or diverged sharply. > ``` *** > [card] [Executive Explorer Dashboard](/mcp/workflows/executive-explorer-dashboard) > > The full workflow version of the dashboard-building prompt above, with a structured tile proposal step. > [card] [Rankings & Priority Lists](/mcp/prompts/rankings) > > For a ranked table instead of a chart, when you need to triage rather than visualize. # White Space & Growth Opportunities Source: https://developers.scrunch.com/mcp/prompts/white-space MCP prompts that surface uncontested AI search territory — queries where neither you nor competitors appear yet, ranked by first-mover value. White space in AI search is where no brand has established authority yet. These prompts identify that territory, track how emerging topics are developing, and surface the audience segments with the lowest AI coverage. *** > [accordion] Find Uncontested Territory in Your Category > > Queries where AI has no clear brand to reference — \[brand name]'s first-mover opportunity. > > ```text theme={null} > For [brand name], I want to find prompts where neither [brand name] nor its top competitors appear in AI responses. > > Pull variants where: > - brand_present = false > - branded = false > > Then cross-reference by pulling variants from this set where competitor_present is also false for the top 3 competitors. > > These are uncontested queries — topics where AI has no clear brand to reference. Group by tag and identify the 3 most commercially relevant white space clusters where [brand name] could be first to establish a presence. > ``` > [accordion] Track Emerging Topics Before Competitors Do > > Recently added prompts — is \[brand name] keeping pace with how its category is evolving in AI search? > > ```text theme={null} > For [brand name], pull variants sorted by created_at descending — the most recently added prompts. Limit to 50. > > For this set: > 1. What new topics or question types are being tracked? > 2. Which of these new prompts have brand_present = true vs. false? > 3. Are there new topic areas where [brand name] is not yet appearing? > > This shows whether [brand name]'s visibility is keeping pace with how its category is evolving in AI search. > ``` > [accordion] Find Audience Segments With No AI Coverage > > Which buyer personas are asking questions that \[brand name] isn't answering anywhere in AI responses? > > ```text theme={null} > For [brand name], pull prompt variants and identify which ones have a persona assigned. For persona-filtered prompts where brand_present = false, tell me: > 1. Which personas are asking questions that [brand name] isn't answering in AI? > 2. Which personas have the highest gap rate? > 3. What types of questions is each persona asking that [brand name] should be addressing? > > These gaps represent audience segments where [brand name] has no AI visibility. > ``` *** > [card] [Prompt Management](/mcp/prompts/configuration) > > Once you've found the white space, use configuration prompts to add and tag new prompts. > [card] [New Brand Live in One Conversation](/mcp/workflows/new-brand-live) > > Setting up a new brand? Seed an initial prompt library covering white space from day one. # Connect your AI tool to the Scrunch MCP Source: https://developers.scrunch.com/mcp/setup Step-by-step setup to connect the Scrunch MCP server to Claude, ChatGPT, Grok, and other AI tools using OAuth in 5 minutes. All setup flows connect to the same server and use the same OAuth sign-in — your Scrunch account credentials, no API key required. Pick your AI client below. > [!NOTE] > > **MCP server URL** > > ```text theme={null} > https://app.scrunchai.com/api/mcp > ``` > > All platforms below use this URL. Authentication happens via Scrunch's standard OAuth sign-in flow; no API key or shared secret is needed. > [tab] Claude > > Scrunch works in the Claude apps and in Claude Code. Expand the one you use. > > > [accordion] Claude > > > > Custom connectors work across Free, Pro, Max, Team, and Enterprise Claude plans. How you add Scrunch depends on whether you're on a personal plan or part of a Team or Enterprise organization. > > > > > [accordion] Personal (Free, Pro, Max) > > > > > > Free plans are limited to one active custom connector at a time. > > > > > > **1. Open Customize** > > > > > > In the Claude web app ([claude.ai](https://claude.ai)) or Claude desktop app, click **Customize** in the sidebar navigation. > > > > > > ![Claude Customize setting](https://mintcdn.com/scrunchai/ak5yAmkXHU_XWgdE/images/claude-customize.png?fit=max\&auto=format\&n=ak5yAmkXHU_XWgdE\&q=85\&s=c335fa3071454d9aa060a98b0f198b11) > > > > > > **2. Go to Connectors** > > > > > > In the Settings sidebar, select **Connectors**. You'll see built-in connectors (Google Drive, Slack, Notion, etc.) followed by any custom connectors you've already added. > > > > > > ![Claude connectors setting](https://mintcdn.com/scrunchai/ak5yAmkXHU_XWgdE/images/claude-connectors.png?fit=max\&auto=format\&n=ak5yAmkXHU_XWgdE\&q=85\&s=e1c3b71a5ce04c7e076d486c84f4c59c) > > > > > > **3. Add a custom connector** > > > > > > Click the **+** button and select **Add custom connector**. > > > > > > **4. Fill in the connector details** > > > > > > In the dialog that opens, enter: > > > > > > * **Name:** `Scrunch AI` (or whatever you'd like to call it) > > > * **Remote MCP server URL:** `https://app.scrunchai.com/api/mcp` > > > * **OAuth Client ID / Client Secret:** Leave blank. These are only needed if you're hosting your own OAuth provider. > > > > > > ![claude-custom-connector](https://mintcdn.com/scrunchai/ak5yAmkXHU_XWgdE/images/claude-custom-connector.png?fit=max\&auto=format\&n=ak5yAmkXHU_XWgdE\&q=85\&s=665155a76bd9e9b7a4c9942e5cbbd634) > > > > > > **5. Click Add, then sign in to Scrunch** > > > > > > Claude redirects you to Scrunch to authenticate. Sign in with your Scrunch account, approve the connection, and Claude returns to the Connectors page with the connector active. > > > > > [accordion] Team & Enterprise — Owners > > > > > > On Team and Enterprise plans, only **owners** can add custom connectors. Once added, the connector becomes available for all members in your organization to enable. > > > > > > **1. Open Organization settings** > > > > > > In the Claude web app ([claude.ai](https://claude.ai)) or Claude desktop app, go to **Organization settings → Connectors**, under **Libraries & Access**. Owners add org-wide connectors here — not from the personal **Customize** page. > > > > > > ![Claude organization settings Connectors](https://mintcdn.com/scrunchai/BlreG_8rN6tDR7ut/images/claude-org-settings-connectors.png?fit=max\&auto=format\&n=BlreG_8rN6tDR7ut\&q=85\&s=3a691d47315f0b17828bfbc40c1f74fd) > > > > > > **2. Add a custom connector** > > > > > > Click **+ Add**, hover over **Custom**, then select **Web**. > > > > > > ![Claude Add Custom Web menu](https://mintcdn.com/scrunchai/BlreG_8rN6tDR7ut/images/claude-org-add-custom-web.png?fit=max\&auto=format\&n=BlreG_8rN6tDR7ut\&q=85\&s=aba7d95253d79976c28de60cf8418caa) > > > > > > **3. Fill in the connector details** > > > > > > In the dialog that opens, enter: > > > > > > * **Name:** `Scrunch AI` > > > * **Remote MCP server URL:** `https://app.scrunchai.com/api/mcp` > > > * **OAuth Client ID / Client Secret:** Under **Advanced settings**, leave both blank. Scrunch supports OAuth Dynamic Client Registration, so Claude registers itself. > > > * **Connection methods:** leave **Individual sign-in** on. Each member then signs in with their own Scrunch account, so brand access and permissions follow the individual — not you. > > > > > > ![Claude Add custom connector dialog](https://mintcdn.com/scrunchai/BlreG_8rN6tDR7ut/images/claude-org-custom-connector-dialog.png?fit=max\&auto=format\&n=BlreG_8rN6tDR7ut\&q=85\&s=457af140704d67b714f6d5153f3bbd03) > > > > > > **4. Click Add, then sign in to Scrunch** > > > > > > Claude redirects you to Scrunch to authenticate. Sign in with your Scrunch account and approve the connection. The Scrunch connector is now available for members in your organization. > > > > > [accordion] Team & Enterprise — Members > > > > > > Regular members on Team and Enterprise plans cannot add custom connectors — that's restricted to org owners. Once an owner has added Scrunch, you can enable it for your own account. > > > > > > **1. Ask an owner to add Scrunch** > > > > > > Have an org owner follow the **Team & Enterprise — Owners** tab to add the Scrunch connector. They only need to do this once for the whole organization. > > > > > > **2. Open Customize → Connectors** > > > > > > Once the connector has been added, go to **Customize → Connectors** in your Claude account. Scrunch AI will appear in the list. > > > > > > **3. Connect and authenticate** > > > > > > Find **Scrunch AI** in the list — it carries a **Custom** label — and click **Connect**. Claude redirects you to Scrunch to sign in with your own Scrunch account. Your individual brand access and permissions are determined by your Scrunch account — not the owner's. > > > > > [!TIP] > > > > > > **Enabling the connector in a chat** — When you start a new conversation, click the connector icon in the message composer and toggle **Scrunch AI** on for that chat. To enable it by default for all new chats, go to **Settings → Connectors → Configure** on the Scrunch AI connector. > > > [accordion] Claude Code > > > > Claude Code is the Claude CLI tool. Run the following command in your terminal: > > > > ```bash theme={null} > > claude mcp add --transport http scrunch https://app.scrunchai.com/api/mcp > > ``` > > > > Then run `/mcp` inside Claude Code, select **scrunch**, and follow the sign-in flow to authenticate with your Scrunch account. > > > > > [!TIP] > > > > > > Add `--scope user` to make Scrunch available in every project, or `--scope project` to share it with your team through a committed `.mcp.json` file. The default (`local`) keeps it to you, in the current project. > > > > **Verify the connection:** > > > > ```text theme={null} > > List my Scrunch brands > > ``` > > > > Your assistant should respond with the brands accessible in your Scrunch org. > [tab] ChatGPT > > OpenAI offers three ways to use Scrunch: in ChatGPT itself, with always-on Dots agents, and in the Codex coding agent. All three connect to the same MCP server. Expand the one you use. > > > [accordion] ChatGPT > > > > Requires a paid ChatGPT plan (Plus, Pro, Team, Enterprise, or Edu). Plus and Pro accounts get read-only access; Team, Enterprise, and Edu accounts get full read + write access. > > > > > [!WARNING] > > > > > > **Critical:** You must remove `openid` from the OAuth scopes in **two separate places** during setup (steps 5 and 6 below). If you miss either one, authentication will fail. > > > > **1. Open Settings → Apps → Advanced Settings** > > > > Click your profile picture in ChatGPT and choose **Settings**. Open the **Apps** tab, then click **Advanced Settings** at the bottom. > > > > ![Screenshot 2026 05 14 At 8 58 59 AM](https://mintcdn.com/scrunchai/ak5yAmkXHU_XWgdE/images/Screenshot-2026-05-14-at-8.58.59-AM.png?fit=max\&auto=format\&n=ak5yAmkXHU_XWgdE\&q=85\&s=1153b0f11661237675d127efdc02207a) > > > > **2. Enable Developer Mode** > > > > In Advanced Settings, toggle **Developer Mode** on. Workspace owners can also enable this org-wide under **Workspace Settings → Permissions & Roles → Connected Data → Developer mode**. > > > > ![Screenshot 2026 05 14 At 8 59 23 AM](https://mintcdn.com/scrunchai/ak5yAmkXHU_XWgdE/images/Screenshot-2026-05-14-at-8.59.23-AM.png?fit=max\&auto=format\&n=ak5yAmkXHU_XWgdE\&q=85\&s=1f5b33c08d75c8e1e85a892bfeb37dea) > > > > **3. Go back to Apps and find Create app** > > > > Navigate back to the main **Apps** tab. With Developer Mode enabled, a **Create app** widget appears. > > > > ![Screenshot 2026 05 14 At 8 56 25 AM](https://mintcdn.com/scrunchai/ak5yAmkXHU_XWgdE/images/Screenshot-2026-05-14-at-8.56.25-AM.png?fit=max\&auto=format\&n=ak5yAmkXHU_XWgdE\&q=85\&s=2a9b843194c607d7b4e0f1ba93a6729f) > > > > **4. Create a new app** > > > > Click **Create app** and fill in: > > > > * **Name / icon / description:** Anything you like — `Scrunch AI` works well. > > * **MCP Server URL:** `https://app.scrunchai.com/api/mcp` > > * **Authentication:** OAuth > > > > **5. Remove openid from Scopes** > > > > Inside the Create app form, expand **Advanced settings**. In the **Scopes** field, deselect or delete `openid`. Leave all other default scopes. > > > > **6. Remove openid from OIDC scope supported** > > > > Still in Advanced settings, scroll to the bottom. Find the **OIDC scope supported** field and delete `openid` from that field as well. Both removals are required. > > > > **7. Confirm and create** > > > > Check the trust acknowledgment and click **Create**. ChatGPT redirects you to Scrunch to authenticate. Sign in and approve the connection. > > > > **8. Use it in a chat** > > > > In any new chat, click the **apps / +** menu in the composer, choose **Developer mode**, and select **Scrunch AI**. > > > > > [!TIP] > > > > > > **Plan limits** — Plus and Pro accounts have read-only access. Features like `list_brands` and `get_presence_metrics` work on any plan, but operations that modify data — `create_brand`, `archive_prompt`, `update_tags` — require a Team, Business, Enterprise, or Edu workspace. > > > [accordion] ChatGPT Dots > > > > Dots are ChatGPT's always-on agents. Each Dot runs on its own cloud computer and works with the apps connected to your ChatGPT account, so you connect Scrunch to ChatGPT first, then give your Dot access to it. Dots are available on ChatGPT Pro and Business Premium, and on Enterprise and Edu workspaces where an admin has turned them on. > > > > **1. Connect Scrunch to ChatGPT** > > > > Follow the **ChatGPT** section above to add Scrunch as a custom app, including removing `openid` from both scope fields. Dots use the same connection. > > > > **2. Give your Dot access to Scrunch** > > > > Open your Dot's settings on ChatGPT desktop web or the desktop app, and under **Plugins** (or **Apps**) connect **Scrunch AI** to that Dot. Only connect the apps the Dot needs. > > > > **3. Paste this prompt into your Dot** > > > > ```text wrap theme={null} > > Set up Scrunch for me. > > > > 1. Use the Scrunch AI app that's connected to my ChatGPT account. It's a remote MCP server at https://app.scrunchai.com/api/mcp. If it isn't available to you yet, tell me exactly which step I need to finish and wait while I do it. > > > > 2. Install the Scrunch Agent Skills so you know how to do Scrunch tasks well. Run `npx skills add https://developers.scrunch.com`. If that doesn't work, read https://developers.scrunch.com/.well-known/skills/index.json and save each skill it lists. > > > > 3. Once you're connected, list my Scrunch brands. Then suggest three useful things you could do with my Scrunch data and ask which one I'd like to start with. > > ``` > > > > > [!NOTE] > > > > > > Your Dot sees the brands and permissions of the Scrunch account you signed in with, and the plan limits in the **ChatGPT** section apply: Plus and Pro accounts get read-only access, while Team, Enterprise, and Edu workspaces get full read and write access. To learn more about what the skills cover, see [Agent Skills](/mcp/skills/overview). > > > [accordion] Codex > > > > Codex is OpenAI's coding agent. It reads MCP servers from `~/.codex/config.toml`, or from `.codex/config.toml` in a project root if you want to share the setup with your team. > > > > **1. Add Scrunch to your config** > > > > Add the server to `config.toml`: > > > > ```toml theme={null} > > [mcp_servers.scrunch] > > url = "https://app.scrunchai.com/api/mcp" > > scopes = ["profile", "email", "offline_access"] > > ``` > > > > Or add it from the terminal with the same settings: > > > > ```bash theme={null} > > codex mcp add scrunch --url https://app.scrunchai.com/api/mcp --scopes profile email offline_access > > ``` > > > > The `scopes` line pins the OAuth scopes to the three Scrunch's sign-in flow grants, so the client never asks for `openid`. See [Troubleshooting](#troubleshooting). > > > > **2. Authenticate** > > > > Run the login command and complete the sign-in with your Scrunch account: > > > > ```bash theme={null} > > codex mcp login scrunch > > ``` > > > > > [!TIP] > > > > > > Prefer the Codex desktop app? Go to **Settings → MCP servers → Add server**, choose **Streamable HTTP**, and enter `https://app.scrunchai.com/api/mcp`. > > > > **Verify the connection:** > > > > ```text theme={null} > > List my Scrunch brands > > ``` > [tab] Perplexity > > Custom remote connectors require a Perplexity Pro, Max, or Enterprise plan. On Enterprise, an admin has to enable custom connectors before members can add their own. > > **1. Open Connectors** > > For your own account, go to **Account settings → Connectors**. Enterprise admins adding Scrunch for the whole organization go to **Enterprise settings → Permissions → Connectors permissions** instead. > > **2. Add a custom connector** > > Click **+ Custom connector** in the top-right corner, then select **Remote** in the dialog. > > **3. Fill in the connector details** > > Enter: > > * **Name:** `Scrunch AI` > * **MCP Server URL:** `https://app.scrunchai.com/api/mcp` > * **Description:** `AI brand monitoring and analytics` (optional, but it helps Perplexity decide when to reach for Scrunch) > * **Authentication:** OAuth — leave Client ID and Client Secret empty. Scrunch supports Dynamic Client Registration, so Perplexity registers itself. > * **Transport:** Streamable HTTP > > **4. Acknowledge and add** > > Check the acknowledgement box confirming you understand the risks of custom connectors, then click **Add**. Scrunch AI appears in your Connectors list. > > **5. Authenticate** > > Click the Scrunch AI connector card to start the sign-in flow. Sign in with your Scrunch account and approve the connection. > > > [!NOTE] > > > > **Enterprise rollout** — adding a connector doesn't share it. The creator has to share it with the organization from the **Permissions** screen in Enterprise settings before teammates can see it, and org-wide connectors may take a moment to appear for everyone. An admin can either authenticate once on the organization's behalf or require each member to sign in individually — require individual sign-in, so each person's brand access and permissions come from their own Scrunch account. > [tab] Grok > > xAI offers Grok (chat) and Grok Bot (an autonomous agent). Both connect to the same MCP server. Expand the one you use. > > > [accordion] Grok > > > > Grok (grok.com / xAI) supports custom MCP connectors on all paid plans. Free users may have limited or no access to custom connectors. > > > > **1. Go to Connectors** > > > > Log in to [grok.com](https://grok.com) and navigate to **Connectors** (direct link: [grok.com/connectors](https://grok.com/connectors) or via the main menu). > > > > ![Grok connectors](https://mintcdn.com/scrunchai/eEie11k8RqXVQIyk/images/grok-connectors.png?fit=max\&auto=format\&n=eEie11k8RqXVQIyk\&q=85\&s=f799d0f35139372a76044d57986770a8) > > > > **2. Add a new custom connector** > > > > Click **New Connector** (or the equivalent + button), then select **Custom**. > > > > ![Grok new connector](https://mintcdn.com/scrunchai/Xn4EEeBaa2q1GkTh/images/Screenshot-2026-05-14-at-9.22.36-AM.png?fit=max\&auto=format\&n=Xn4EEeBaa2q1GkTh\&q=85\&s=2f75bdab8bc911431ccc24ce1a476ca2) > > > > **3. Fill in the connector details** > > > > Enter: > > > > * **Name:** `Scrunch AI` (or your preferred name) > > * **MCP Server URL:** `https://app.scrunchai.com/api/mcp` > > > > Leave any OAuth Client ID / Secret fields blank unless instructed otherwise (Scrunch handles authentication via its standard OAuth flow). > > > > ![Grok custom connector](https://mintcdn.com/scrunchai/Xn4EEeBaa2q1GkTh/images/Screenshot-2026-05-14-at-9.23.05-AM.png?fit=max\&auto=format\&n=Xn4EEeBaa2q1GkTh\&q=85\&s=5c7e7346233b1f8d8366f5056beed4cc) > > > > **4. Save and authenticate** > > > > Click **Add** / **Create**. Grok will redirect you to Scrunch to sign in with your Scrunch account and approve the connection. Once approved, the connector becomes active. > > > > > [!TIP] > > > > > > **Enabling in a chat** — In a new conversation, look for the connector / tools icon or sidebar. Toggle **Scrunch AI** on for that chat. You can set it as default for new chats in the connector settings. > > > > > [!NOTE] > > > > > > **MCP server URL:** `https://app.scrunchai.com/api/mcp`\ > > > Authentication uses Scrunch's standard OAuth sign-in. No API key is required. > > > [accordion] Grok Bot > > > > Grok Bot is xAI's autonomous agent app. It sets up new tools when you ask it to, so there's no settings screen to find — paste the prompt below into a chat with your Bot and it connects Scrunch for you. > > > > **1. Paste this prompt into Grok Bot** > > > > ```text wrap theme={null} > > Set up Scrunch for me. > > > > 1. Connect the Scrunch MCP server. It's a remote MCP server named "Scrunch AI" at https://app.scrunchai.com/api/mcp (Streamable HTTP, OAuth sign-in, no API key). When it needs me to sign in, give me the link and wait while I log in to my Scrunch account and approve the connection. > > > > 2. Install the Scrunch Agent Skills so you know how to do Scrunch tasks well. Run `npx skills add https://developers.scrunch.com`. If that doesn't work, read https://developers.scrunch.com/.well-known/skills/index.json and save each skill it lists. > > > > 3. Once you're connected, list my Scrunch brands. Then suggest three useful things you could do with my Scrunch data and ask which one I'd like to start with. > > ``` > > > > **2. Sign in to Scrunch** > > > > When Grok Bot sends you the sign-in link, open it, sign in with your Scrunch account, and approve the connection. You don't need a Client ID or Client Secret — Scrunch supports OAuth Dynamic Client Registration. > > > > **3. Pick a starting point** > > > > Once connected, your Bot lists your Scrunch brands and suggests where to start. Reply with the one you want. > > > > > [!NOTE] > > > > > > Grok Bot runs on its own cloud computer, so it can only reach public HTTPS servers — Scrunch's MCP URL qualifies. To learn more about what the skills cover, see [Agent Skills](/mcp/skills/overview). > [tab] Muse > > Meta offers the Muse app and Muse Code, its terminal coding agent. Both connect to the same MCP server. Expand the one you use. > > > [accordion] Muse > > > > Muse is Meta's personal AI agent. It doesn't have a connector settings screen for remote MCP servers — instead, you ask Muse in chat to build a custom connector. Paste the prompt below into a new Muse chat and it handles the rest. > > > > **1. Paste this prompt into Muse** > > > > ```text wrap theme={null} > > Set up Scrunch for me. > > > > 1. Create a Custom Connector for a new remote MCP server. Name: scrunch. Transport: remote streamable HTTP. URL: https://app.scrunchai.com/api/mcp. Authentication: OAuth (no API key). When it needs me to sign in, give me the link and wait while I log in to my Scrunch account and approve the connection. > > > > 2. Install the Scrunch Agent Skills so you know how to do Scrunch tasks well. Run `npx skills add https://developers.scrunch.com`. If that doesn't work, read https://developers.scrunch.com/.well-known/skills/index.json and save each skill it lists. > > > > 3. Once you're connected, list my Scrunch brands. Then suggest three useful things you could do with my Scrunch data and ask which one I'd like to start with. > > ``` > > > > **2. Sign in to Scrunch** > > > > Muse prompts you to approve the connection. Sign in with your Scrunch account on the page that opens. You don't need a Client ID or Client Secret — Scrunch supports OAuth Dynamic Client Registration. > > > > **3. Pick a starting point** > > > > Once connected, Muse lists your Scrunch brands and suggests where to start. Reply with the one you want. > > > > > [!NOTE] > > > > > > Muse connects from Meta's cloud, so it can only reach public HTTPS servers — Scrunch's MCP URL qualifies. Meta doesn't publish a setup guide for custom MCP connectors in the consumer Muse app, and this flow may change. If Muse can't complete the sign-in, contact [support@scrunchai.com](mailto:support@scrunchai.com). To learn more about what the skills cover, see [Agent Skills](/mcp/skills/overview). > > > [accordion] Muse Code > > > > Muse Code is Meta's terminal coding agent. It reads MCP servers from your settings file at `~/.config/muse/settings.json`. > > > > **1. Add Scrunch to your settings file** > > > > Add a `mcp_servers` entry. The file must also set `"schema_version": 1`, so keep that key if it's already there: > > > > ```json theme={null} > > { > > "schema_version": 1, > > "mcp_servers": { > > "scrunch": { > > "transport": "streamable_http", > > "url": "https://app.scrunchai.com/api/mcp", > > "headers": {}, > > "enabled": true, > > "mode": "optional" > > } > > } > > } > > ``` > > > > `mode` controls what happens when Scrunch is unreachable: `optional` lets the session continue with a warning, while `required` aborts it. > > > > **2. Authenticate** > > > > Run the login command and sign in with your Scrunch account: > > > > ```bash theme={null} > > muse mcp login scrunch > > ``` > > > > Muse Code refreshes the token automatically after that. Use `/mcp` in a session to see Scrunch and its tools in the live server list. > > > > **Verify the connection:** > > > > ```text theme={null} > > List my Scrunch brands > > ``` > > > > > [!WARNING] > > > > > > MCP tools run outside Muse Code's filesystem and network sandbox, so only connect servers you trust. > [tab] Cursor > > Cursor manages MCP servers from the **Customize** page in the sidebar. Marketplace plugins install with one click; a custom remote server like Scrunch is added by creating an `mcp.json` file. > > **1. Create your mcp.json** > > Add `.cursor/mcp.json` in your project root for a single project, or `~/.cursor/mcp.json` in your home directory to make Scrunch available in every workspace: > > ```json theme={null} > { > "mcpServers": { > "scrunch": { > "url": "https://app.scrunchai.com/api/mcp", > "auth": { > "scopes": ["profile", "email", "offline_access"] > } > } > } > } > ``` > > The `url` field is what marks this as a remote server — there's no transport type to choose. Scrunch serves Streamable HTTP. > > **2. Authenticate** > > Save the file. On first use, Cursor prompts you to sign in with your Scrunch account over OAuth. You don't need a Client ID or Client Secret — Scrunch supports OAuth Dynamic Client Registration, so Cursor registers itself. > > **3. Check it in Customize** > > Open **Customize** in the sidebar and select the **MCPs** filter. Once Cursor has read the file and you've signed in, **scrunch** appears under **Connected** with its full tool count — this is also where you toggle it off when you don't need it. > > ![Cursor Customize MCPs view showing scrunch connected with 45 tools enabled](https://mintcdn.com/scrunchai/BlreG_8rN6tDR7ut/images/cursor-customize-mcp.png?fit=max\&auto=format\&n=BlreG_8rN6tDR7ut\&q=85\&s=ca32941b7748c31022a9e75929745d86) > > Still seeing the **Connect External Tools with MCP** empty state instead? Cursor hasn't picked up your `mcp.json` yet — check that the file is saved, then reopen Customize. > > **Verify the connection:** > > ```text theme={null} > List my Scrunch brands > ``` > > > [!WARNING] > > > > **Keep the `scopes` list — don't drop the `auth` block.** Without it, Cursor discovers scopes automatically and requests `openid`, which Scrunch's sign-in flow rejects. Authentication then stalls on **Waiting for callback…** and your browser shows *"Authorization session ended."* Pinning the three scopes above is what makes the flow complete. > > > > You still don't need a `CLIENT_ID` or `CLIENT_SECRET` — Scrunch supports Dynamic Client Registration, so Cursor registers itself. `scopes` is the only `auth` field required. > > > [!TIP] > > > > **Already hit the error?** Cursor caches the registration it made the first time, so fixing `mcp.json` alone isn't enough. Open the server's **Configure** dialog and click **Reload** to re-register with the corrected scopes. > > > [!NOTE] > > > > **Looking at Cursor Settings → Tools & MCPs?** That page is being retired — a banner at the top of it now points you to **Customize**. Either surface manages the same servers, but `mcp.json` is the only place to add a custom remote server like Scrunch; there's no form for it. > > > [!NOTE] > > > > **Team and Enterprise customers** — a Cursor admin can distribute Scrunch to everyone instead of each person writing their own `mcp.json`. Add the server under **Dashboard → Integrations & MCP**, then choose **Add to Team Marketplace** so teammates can install it from **Customize**. Each teammate still signs in with their own Scrunch account, so brand access and permissions stay per-user. > [tab] Devin > > Devin is Cognition's AI software engineering agent. It connects to remote MCP servers from its settings. > > **1. Add a custom MCP** > > In Devin, go to **Settings → Connections → MCP servers**, then select **Add a custom MCP**. > > **2. Fill in the server details** > > Enter: > > * **Name:** `Scrunch AI` > * **Transport:** HTTP > * **Server URL:** `https://app.scrunchai.com/api/mcp` > * **Authentication:** OAuth > > **3. Choose Personal access** > > Select **Personal** so each person signs in with their own Scrunch account and sees only their own brands. > > **4. Save and sign in** > > Save the server, then complete the OAuth flow when Devin prompts you. > > > [!NOTE] > > > > **Organization access shares one sign-in.** With **Organization** access, every member of your Devin workspace uses a single authenticated Scrunch connection, so brand access follows whoever signed in — not each individual. Choose **Personal** unless you specifically want that. > [tab] Antigravity > > Antigravity is Google's agentic coding platform. Add Scrunch as a custom server — don't use the pre-configured connectors in its MCP gallery. > > **1. Open the raw config** > > In the agent side panel, click **…**, choose **MCP Servers**, then **Manage MCP Servers**, then **View raw config**. This opens `mcp_config.json`, which lives at `~/.gemini/config/mcp_config.json` globally or `.agents/mcp_config.json` in a workspace. > > **2. Add Scrunch** > > Add the server. Antigravity uses `serverUrl` for remote servers — a plain `url` field isn't supported: > > ```json theme={null} > { > "mcpServers": { > "scrunch": { > "serverUrl": "https://app.scrunchai.com/api/mcp" > } > } > } > ``` > > **3. Authenticate** > > Save the file. Antigravity prompts you to sign in with your Scrunch account. If it doesn't, open **Agent Settings → Customizations** and click **Authenticate** next to **scrunch**. You don't need a Client ID or Client Secret — Scrunch supports OAuth Dynamic Client Registration. > > **Verify the connection:** > > ```text theme={null} > List my Scrunch brands > ``` > > > [!WARNING] > > > > **Known Antigravity issue.** At the time of writing, Antigravity (v1.0.0 and the 2.0 IDE) can complete the OAuth sign-in and then send its first request without the access token. A direct `serverUrl` connection then fails with `calling "initialize": sending "initialize": Unauthorized`. This affects any OAuth-protected MCP server, not just Scrunch. If you see that error, use the workaround below. > > **Workaround: connect through `mcp-remote`** > > [`mcp-remote`](https://github.com/geelen/mcp-remote) is a small local bridge that handles the OAuth sign-in itself and presents Scrunch to Antigravity as a local server. Replace the `scrunch` entry in `mcp_config.json` with: > > ```json theme={null} > { > "mcpServers": { > "scrunch": { > "command": "npx", > "args": [ > "-y", > "mcp-remote", > "https://app.scrunchai.com/api/mcp", > "--static-oauth-client-metadata", > "{\"scope\":\"profile email offline_access\"}" > ] > } > } > } > ``` > > Restart Antigravity. On first use, your browser opens so you can sign in with your Scrunch account. This needs Node.js installed. The `--static-oauth-client-metadata` argument pins the OAuth scopes to the three Scrunch's sign-in flow grants, so the client never requests `openid`. > > > [!TIP] > > > > To retry from a clean state, delete the cached sign-in with `rm -rf ~/.mcp-auth` and restart Antigravity. > [tab] VS Code > > Create a `.vscode/mcp.json` file in your workspace root with the following content: > > ```json theme={null} > { > "servers": { > "scrunch": { > "type": "http", > "url": "https://app.scrunchai.com/api/mcp" > } > } > } > ``` > > Save the file. VS Code (with GitHub Copilot) will detect the MCP configuration and prompt you to authenticate with Scrunch on first use. > > > [!TIP] > > > > To share the configuration across your team, commit `.vscode/mcp.json` to your repository. > [tab] Copilot Studio > > Microsoft Copilot Studio lets you attach the Scrunch MCP to any custom agent. You'll need an agent already created before connecting Scrunch to it. > > > [!WARNING] > > > > **Prerequisite:** the agent must have **generative orchestration** turned on. MCP tools are unavailable without it. > > **1. Open your agent** > > In Microsoft Copilot Studio, open the agent you want to extend with Scrunch. From the agent's left navigation, choose **Tools**. > > **2. Add a new tool** > > Click **+ Add a tool**. In the dialog, choose **New tool**, then select **Model Context Protocol**. This launches the MCP onboarding wizard. > > **3. Fill in the wizard** > > Provide: > > * **Server name:** `Scrunch AI` > * **Server description:** `AI brand monitoring and analytics` > * **Server URL:** `https://app.scrunchai.com/api/mcp` > > The description matters — the agent's orchestrator uses it to decide whether to call Scrunch at runtime. > > **4. Choose OAuth 2.0 → Dynamic discovery** > > For **Authentication**, select **OAuth 2.0**, then set the **Type** to **Dynamic discovery**. Scrunch supports Dynamic Client Registration with discovery, so Copilot Studio finds the endpoints and registers itself — you don't need to enter a Client ID, Client Secret, or any URLs. > > **5. Authenticate** > > Click **Create**, then **Next**. On the **Add tool** dialog, choose **Create a new connection**. Copilot Studio redirects you to Scrunch to authenticate — sign in with your Scrunch account and approve the connection. > > **6. Add features to your agent** > > After connecting, you'll see the full list of Scrunch features. Select which ones the agent should have access to, click **Add to agent**, then save and publish your agent. > > > [!TIP] > > > > **Editing the connector later** — If you need to update the connector details (e.g., swap to a different Scrunch account), open **Power Apps → Custom connectors**, find the Scrunch entry, and update there. The change propagates back into Copilot Studio automatically. > [accordion] Using a different MCP client > > Any client that supports remote MCP servers over **Streamable HTTP** and OAuth can connect to Scrunch. Add a server with this URL: > > ```text theme={null} > https://app.scrunchai.com/api/mcp > ``` > > Most clients accept a JSON configuration along these lines, though the exact keys vary by client — some use `url`, some `serverUrl`, and VS Code wants `servers` rather than `mcpServers`: > > ```json theme={null} > { > "mcpServers": { > "scrunch": { > "url": "https://app.scrunchai.com/api/mcp" > } > } > } > ``` > > Scrunch supports OAuth Dynamic Client Registration, so you shouldn't need a Client ID or Client Secret. If your client lets you set OAuth scopes, pin them to `profile`, `email`, and `offline_access` — see [Troubleshooting](#troubleshooting). > > > [accordion] My client only supports local (stdio) servers > > > > Bridge to Scrunch with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which runs locally and forwards to the remote server: > > > > ```json theme={null} > > { > > "mcpServers": { > > "scrunch": { > > "command": "npx", > > "args": ["-y", "mcp-remote", "https://app.scrunchai.com/api/mcp"] > > } > > } > > } > > ``` > > > > The first run opens your browser to sign in with your Scrunch account. This needs Node.js installed. *** ## Troubleshooting | Symptom | Likely cause | Fix | | - | - | - | | Authentication fails immediately | Signed in with the wrong account | Sign out of Scrunch in your browser, then reconnect using the correct account | | "No brands found" | Your Scrunch account has no brand access | Ask your org admin to grant you access to at least one brand | | ChatGPT auth fails | `openid` not removed from both scope fields | Recreate the app and follow steps 5–6 carefully | | Cursor stalls on "Waiting for callback…" and the browser shows "Authorization session ended" | The `auth.scopes` block is missing, so Cursor requested `openid` | Add `"auth": {"scopes": ["profile", "email", "offline_access"]}` to your `mcp.json`, then click **Reload** in the server's Configure dialog | | Any client fails with `invalid_scope` | The client requested `openid`, which Scrunch's sign-in flow doesn't grant | Pin the connector's scopes to `profile`, `email`, `offline_access` wherever the client allows it | | Tools not appearing in Claude | Connector not enabled for this chat | Click the connector icon in the composer and toggle Scrunch AI on | | Client only supports local (stdio) servers | It can't make remote HTTP connections | Use the `mcp-remote` bridge described under [Using a different MCP client](#using-a-different-mcp-client) | | Antigravity fails with `calling "initialize": sending "initialize": Unauthorized` | A known Antigravity bug: it signs in, then sends the first request without the token | Use the `mcp-remote` workaround on the Antigravity tab | | Free Claude plan limit | Free plan is limited to one custom connector | Remove an existing custom connector or upgrade your plan | | Scrunch connector not visible (org member) | Owner hasn't added it to the org yet | Ask an org owner to follow the Team & Enterprise — Owners setup steps | Need more help? Contact your Scrunch CSM or email [support@scrunchai.com](mailto:support@scrunchai.com). *** ## Next steps > [card] [Feature Reference](/mcp/tools) > > Browse all MCP features with descriptions and example prompts for each. > [card] [Agent Skills](/mcp/skills/overview) > > Install skills that set up brands, prompts, and dashboards for your agent. > [card] [Use cases](/mcp/workflows/new-brand-live) > > Step-by-step workflows for reporting, competitive analysis, prompt management, and more. # Scrunch Agent Skills Source: https://developers.scrunch.com/mcp/skills/overview Install Scrunch's Agent Skills — MCP-based or REST-only — for brand setup, prompt libraries, dashboards, page audits, and more. [Agent Skills](https://agentskills.io) are installable packages that teach your AI agent how to work with Scrunch. Once installed, it can set up a brand end to end, build a prompt library, configure citation segments, run page audits, migrate an existing setup, and generate a branded visibility dashboard, all through conversation. ## Get your agent up to speed Copy this prompt into Claude Code, Claude Cowork, Codex, or any Agent Skills-aware client. It installs every Scrunch Skill and has your agent summarize what it can now do: Install Scrunch's Agent Skills into your agent. Install the `skill.md` files from the Mintlify-hosted Scrunch documentation site into my agent context so you know what this product can do. 1. Run `npx skills add https://developers.scrunch.com` 2. Print the list of skills that were installed, including each skill's name and description. 3. Summarize the key capabilities in one paragraph so I know what you can now help me accomplish with this product. 4. If any skill declares required inputs or constraints in its frontmatter, call them out before I ask you to use it. ## Installation To install all available Skills yourself: ```bash theme={null} npx skills add https://developers.scrunch.com ``` Works with Claude Code, Claude Cowork, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, and more. See [all supported agents](https://github.com/vercel-labs/skills?tab=readme-ov-file#supported-agents). Two families install together as one package, and your agent picks the right one. It uses `scrunch-*` whenever the Scrunch MCP server is connected and falls back to `api-*` when it isn't. > [!NOTE] > > `scrunch-*` Skills need the Scrunch MCP server connected. See the [setup guide](/mcp/setup). `api-*` Skills need a Scrunch API key set as `SCRUNCH_API_TOKEN`. See [API authentication](/api-reference/introduction). You can't install just one family, but each Skill checks for its own prerequisite before running. ## Available skills > [tab] MCP-based > > The default when the Scrunch MCP server is connected, with the full product surface: sub-brands, citation segments, geo and industry targeting, bulk operations. No API key needed. > > | Skill | Description | When to use | > | - | - | - | > | `scrunch-brand-setup` | Brand record, competitors, sub-brands and sub-competitors, personas — generated from just a domain | Setting up a brand that doesn't exist in Scrunch yet, or reviewing an existing one against best practices | > | `scrunch-migrate-setup` | Exports a setup from wherever you currently track this, maps it into Scrunch's structure, and reconciles it against your plan limits before creating anything | Only when you're already using a comparable tool and want to bring that setup over — not for a brand-new setup | > | `scrunch-citation-segments` | Groups cited domains into named tiers — Socials, Publications, Marketplaces, Reviews | After a brand exists — proposes sensible defaults automatically, no URL list required | > | `scrunch-prompt-setup` | The actual prompt library — funnel stages, tags, topics, geo-specific coverage, AI platform selection | Building or auditing what Scrunch tracks, or answering "how is my brand doing in AI search" | > | `scrunch-visibility-dashboard` | A repeatable, Scrunch-branded visibility dashboard (presence, citations, sentiment, weakest prompts, agent traffic) as an artifact or HTML file — not an Explorer link | Sharing a visual summary of a brand's AI visibility, e.g. for a QBR or stakeholder update | > | `scrunch-visual-style` | Scrunch's actual typography and color system (Inter, IBM Plex Mono, the Neutrals/Greens/Blues palette) — and the rule against color-coded status badges | Applied by default to any deliverable built from Scrunch MCP data, unless you've specified your own visual style or asked not to use it | > [tab] REST-only > > For agents, scripts, and CI pipelines calling the REST API directly with a `SCRUNCH_API_TOKEN`. A smaller surface than MCP, and each Skill says plainly what it can't do. > > | Skill | Description | When to use | > | - | - | - | > | `api-brand-setup` | Brand record, competitors, and personas via the Configuration API | Setting up or updating a brand when MCP isn't connected — CI, a backend script, an agency onboarding tool | > | `api-prompt-setup` | Adding prompts via the Configuration API | Building a prompt library when MCP isn't connected | > | `api-page-audit` | Queues and retrieves AI-search-readiness audits for specific URLs. **Deprecated** — the Site Audit API it wraps is being retired. | Checking how AI crawlers see a page — no MCP equivalent exists for this today | > | `api-get-started` | Orchestrates brand setup, prompt setup, and page audits into one flow | "Let's get started in Scrunch" / "set me up in Scrunch" when MCP isn't connected | > | `api-dashboard-builder` | The same repeatable visibility dashboard, built entirely from REST API calls | Sharing a visual AI-visibility summary when MCP isn't connected | > | `api-sitemap-export` | Page inventory, audit scores, and CSV/XLSX export of the crawled sitemap. **Deprecated** — the Sitemap API it wraps is being retired. | Content inventory and per-page metrics — no MCP equivalent exists for this today | > | `api-query-metrics` | Ad hoc, custom metric queries via the structured Query API | Custom reporting that goes beyond the standard dashboard shape | > | `api-responses-export` | Raw AI response text and citations, for ETL pipelines | Bulk export or audit of what AI platforms actually said | > | `api-signals-monitoring` | Reads Scrunch's nightly detected-change feed | Feeding a custom alert channel or weekly digest | > | `api-agent-traffic-connect` | Optional — pushes custom AI-crawler traffic data | Seeing which AI agents visit your pages, without a native CDN integration | > | `api-ai-referrals` | Optional — pushes Adobe Analytics-style AI referral data | Powering the AI Traffic dashboard for brands not using Google Analytics 4 | ## Example prompts Once Skills are installed, ask your agent in plain language: > [tab] MCP > > | You say | Skill used | > | - | - | > | "Set up a Scrunch brand for smithoptics.com" | `scrunch-brand-setup` | > | "Set up my brand in Scrunch — here's my website" | `scrunch-brand-setup` | > | "We're switching from our current AI-visibility tool" | `scrunch-migrate-setup` | > | "Import my brand and prompts from \[another tool]" | `scrunch-migrate-setup` | > | "Set up citation segments for \[brand]" | `scrunch-citation-segments` | > | "Segment these publications for \[brand]" | `scrunch-citation-segments` | > | "Build our prompt library" / "Are we showing up in AI search" | `scrunch-prompt-setup` | > | "Which AI platforms should we track" | `scrunch-prompt-setup` | > | "Add prompts for our \[city] location" | `scrunch-prompt-setup` | > | "Build a visibility dashboard for \[brand]" | `scrunch-visibility-dashboard` | > | "Make an HTML citation dashboard I can share" | `scrunch-visibility-dashboard` | > | "Make this on-brand for Scrunch" / "Use Scrunch's colors" | `scrunch-visual-style` | > [tab] REST API > > | You say | Skill used | > | - | - | > | "Set up a Scrunch brand for smithoptics.com" | `api-brand-setup` | > | "Build our prompt library" | `api-prompt-setup` | > | "Build a visibility dashboard for \[brand]" | `api-dashboard-builder` | > | "Run a page audit on our pricing page" | `api-page-audit` — no MCP equivalent | > | "Export our sitemap to a spreadsheet" | `api-sitemap-export` — no MCP equivalent | > | "Let's get started in Scrunch" | `api-get-started` | > [!WARNING] > > Skill discovery depends on your client. Claude Code and Claude Cowork read installed skills automatically once added; some clients need the skill named explicitly the first time ("use the scrunch-brand-setup skill to..."). If nothing triggers, re-run `npx skills add https://developers.scrunch.com` — every Skill is plain markdown, so it's cheap to retry. > [card] [Feature Reference](/mcp/tools) > > Every Scrunch MCP tool the `scrunch-*` Skills call, with descriptions and example prompts. > [card] [API Reference](/api-reference/introduction) > > The REST API the `api-*` Skills call directly, including authentication and scopes. # Scrunch MCP Feature Reference and Example Prompts Source: https://developers.scrunch.com/mcp/tools Reference for 54 Scrunch MCP tools covering reporting, signals, responses, prompts, brand configuration, agent traffic, keyword volume, and help docs, with example prompts. Scrunch's MCP connection gives your AI assistant access to 54 features. These are called automatically in response to natural-language prompts — you never need to reference them by name. Related categories are grouped into the tabs below; use them to jump to what you need. Each description and example prompt shows what a feature does and how to ask for it. > [tab] Reporting > > Everything for measuring and visualizing AI visibility — the core metrics, plus the Explorer charts and dashboards built on top of them. > > ## Metrics > > The four core analytics features. Each accepts the same set of filters: AI platform, country, persona, funnel stage, tags, topics, branded vs. non-branded prompts, and a date range. > > > [accordion] get_presence_metrics > > > > Returns brand mention rate (presence) over time — the percentage of AI responses where your brand is mentioned. Set `include_competitors=true` to compare brands side by side. > > > > **Example prompts** > > > > * "How has our presence in ChatGPT trended over the last 90 days?" > > * "Compare our mention rate vs. all tracked competitors over the past month." > > * "Show me weekly presence for our brand on Perplexity since January." > > > [accordion] get_position_metrics > > > > Returns how often the brand appears in the top, middle, or bottom position within AI responses — relative to other brands mentioned in the same response. > > > > **Example prompts** > > > > * "Are we showing up first or last when AI assistants list options in our category?" > > * "What's our average position on ChatGPT for consideration-stage prompts?" > > > [accordion] get_sentiment_metrics > > > > Returns sentiment breakdown (positive, mixed, negative) for brand mentions in AI responses. > > > > **Example prompts** > > > > * "What's the sentiment trend for our brand on Perplexity in the last 30 days?" > > * "Is sentiment improving or declining compared to last quarter?" > > * "Compare our sentiment vs. our top competitor across all platforms." > > > [accordion] get_citations_metrics > > > > Returns how AI-cited URLs break down by ownership: brand-owned, competitor-owned, and third-party. Use `citation_owner` to focus on one type, or `brand_mentioned` to filter by branded vs. non-branded prompts. > > > > **Example prompts** > > > > * "What share of citations come from third-party sites for our non-branded queries?" > > * "Which competitor's domains are getting cited the most in our category?" > > * "How has our owned citation share changed over the last 60 days?" > > ## Explorer > > Turn a metric question into an interactive Scrunch Explorer chart or a saved dashboard. Both return a deep link that opens the Explorer pre-configured — great for exploring the data behind an answer or saving a view you'll revisit. > > > [accordion] generate_explorer_chart > > > > Builds an Explorer chart from a metric/breakdown/filter spec and returns a deep link that opens the Explorer with that chart already configured. Your assistant offers this after answering an analysis question so you can explore the chart behind the numbers. Supports line, bar, and pivot visualizations, breakdowns (e.g. by platform or competitor), custom date ranges, and comparison overlays. > > > > **Example prompts** > > > > * "Chart our mention rate by AI platform over the last 30 days." > > * "Visualize our share of voice vs. our top 3 competitors, weekly." > > * "Show citations broken down by owner as a bar chart, and give me the link." > > > [accordion] create_explorer_dashboard > > > > Creates a saved dashboard of metric tiles for a brand and returns a deep link to it. Each tile uses the same spec as `generate_explorer_chart` plus a title — mix a few headline "card" tiles with line/bar charts for trends and breakdowns. > > > > **Example prompts** > > > > * "Build a dashboard for Acme Coffee with presence, sentiment, and citation trends." > > * "Create a competitive dashboard comparing our share of voice against Blue Bottle and Stumptown." > > ## Custom queries > > The four metrics features above cover the common questions. When a question needs a combination they don't offer — an unusual grouping, a filter on a computed value, a period-over-period comparison — your assistant composes a query directly. > > > [accordion] query_metrics > > > > Runs an aggregated metrics query against a defined vocabulary of dimensions and metrics. Composed like a SQL `GROUP BY`: dimensions become group-by columns (date, AI platform, prompt topic, competitor) and metrics become the aggregates. Supports filters, filters on aggregate values, period-over-period comparison, and pagination. Defaults to the last 30 days, and every result reports the resolved date range it actually used. > > > > **Example prompts** > > > > * "Break down competitor mention rate by platform and month for Silk." > > * "Which prompt topics have a mention rate above 40%, and how many responses back each one?" > > * "Compare our presence this quarter against last quarter, split by funnel stage." > > > [accordion] get_metric_glossary > > > > Returns exact definitions for every dimension and metric `query_metrics` accepts — what each measures, its unit or scale, and how similar-sounding fields differ. This is the authoritative source for what a Scrunch metric means, so ask for it whenever a number needs interpreting. > > > > **Example prompts** > > > > * "What exactly does presence measure — does a citation of our domain count?" > > * "What's the difference between position and share of voice?" > > * "List every metric I can group by platform." > > ## Saved patterns > > Scrunch ships a curated catalog of query patterns — the same ones behind your dashboard tiles. Your assistant checks these before composing anything from scratch, so answers stay consistent with what the product shows you. > > > [accordion] list_query_patterns > > > > Lists the curated query patterns available for a brand: the question each one answers, the metric fields it uses, and a product link that renders it. When a pattern already answers your question, your assistant points you at the product rather than recomputing the number. > > > > **Example prompts** > > > > * "What standard reports can you run for this brand?" > > * "Is there a saved view for citation ownership over time?" > > > [accordion] get_query_pattern > > > > Returns the full detail for one pattern: a ready-to-run query template, the product share link, and an Explorer deep link where the pattern maps to one. Used to adapt a pattern to different parameters — another topic, competitor, platform, or date range — instead of composing a new query. > > > > **Example prompts** > > > > * "Run the citation-ownership pattern but for the last 7 days." > > * "Take the share-of-voice view and swap in our German competitors." > [tab] Signals > > Signals are metric movements Scrunch has already found for you. A nightly sweep significance-tests changes in your visibility metrics, so "what changed this week?" is a lookup rather than a fishing expedition. Each signal carries a confidence tier and the date it was detected for. > > > [accordion] list_signals > > > > Lists detected signals for a brand — statistically tested level changes and trends in AI-visibility metrics. Filterable by platform, metric, direction, confidence tier, subject, and anchor date range. By default returns the user-facing confidence tiers (high, confident, worth a look, provisional). An ongoing signal re-detects daily, and a multi-day range returns only the latest detection for each one. > > > > **Example prompts** > > > > * "What changed for us this week?" > > * "Any alerts on Perplexity in the last 14 days?" > > * "Show me only high-confidence negative movements." > > > [accordion] get_signal > > > > Fetches one signal in full, including its narrative — what happened, why it matters, and what to do about it. List results carry only the one-line headline, so this is the follow-up when a signal is worth acting on. > > > > **Example prompts** > > > > * "Tell me more about that sentiment drop." > > * "Why does the ChatGPT presence signal matter, and what should we do?" > [tab] Responses > > Pull the raw AI responses Scrunch has captured — full response text, citations, and per-competitor evaluations for individual answers. Use this when you need to read what an AI actually said, not just an aggregate metric. > > > [accordion] list_responses > > > > Lists individual AI responses (observations) for a brand. Filter by platform, prompt, persona, funnel stage, date range, and whether the response includes shopping results. Results are paginated with `limit` (default 10, max 100) and `offset`. > > > > By default it returns observation IDs only, to keep payloads small. Ask for full detail (`ids_only=false`) to include response text, evaluation data, citations, and competitor analysis for every listed response — or fetch IDs first and pull individual responses with `get_response`. > > > > Use this when you want to audit a specific answer, compare what two platforms said about the same prompt, or pull a sample of recent responses for qualitative review. For aggregated trends, use the metrics features instead. > > > > **Example prompts** > > > > * "Show me the 10 most recent ChatGPT responses for Acme Coffee where our brand wasn't mentioned." > > * "Pull every Perplexity response from last week for prompt #482 so I can compare them side by side." > > * "Find responses on Google AI Overviews in the comparison stage that include shopping results." > > * "Give me the raw responses Claude returned for the 'sustainability' persona in April." > > > [accordion] get_response > > > > Fetches a single AI response by ID with full evaluation data, citations, and competitor analysis. Use it to inspect a response ID returned by `list_responses`. > > > > **Example prompts** > > > > * "Pull the full text and citations for response #918273." > > * "What did the AI actually say in that response — and which URLs did it cite?" > [tab] Prompts > > Manage the seed prompts Scrunch runs against AI platforms on your behalf, their funnel stage and topic classification, and the tags you use to organize them. > > ## Prompts > > Browse and manage the seed prompts Scrunch runs against AI platforms on your behalf. `list_prompt_templates` and `list_prompt_variants` cover two different grains — templates are the editable seed prompts you configure; variants are the expanded per-platform/persona/geo executions that actually collect data. > > > [accordion] list_prompt_templates > > > > Lists the brand's configured seed prompt templates (active and paused, never archived) with their current stage, topics, and tags — the read side of bulk labeling: call this to find prompt ids and current labels before a write. Filterable by `prompt_ids` (to verify specific ids rather than paging the whole brand), `status` (active/paused), `stage_id` (`-1` for no stage), `topic_ids` (matches ANY of the given topics), `text_contains` (a literal substring, not semantic search — prefer `topic_ids` for concept questions), and `branded`. Set `ids_only=true` to get every matching id in one unpaginated array, ready to feed straight into a bulk write. > > > > **Example prompts** > > > > * "Which of our prompts have no stage assigned yet?" > > * "Find every active prompt tagged with the 'pricing' topic." > > * "Give me just the ids of every paused prompt — I'm about to reactivate them." > > > [accordion] list_prompt_variants > > > > Lists the prompt variants Scrunch is monitoring for a brand. Filterable by tag, persona, country, branded vs. non-branded, citation domain, funnel stage, and more. > > > > **Example prompts** > > > > * "Show me the top 20 non-branded prompts for Acme Coffee in the US." > > * "List all the prompts tagged 'consideration' for our brand." > > * "Browse the prompts in the awareness stage — I want to see what's covered before I add new ones." > > > [accordion] create_prompt > > > > Adds a new seed prompt for a brand, optionally with category, key topics, persona, platforms, and tags. > > > > **Example prompts** > > > > * "Add a prompt to Acme Coffee: 'What's the best mail-order coffee subscription for offices?' Tag it as 'consideration'." > > * "Create 5 new awareness-stage prompts for Acme Coffee focused on sustainability." > > > [accordion] archive_prompt > > > > Archives (soft-deletes) a seed prompt so it stops running. History is preserved. > > > > **Example prompts** > > > > * "Archive prompt #482 — we don't need to track that one anymore." > > * "Archive all prompts tagged 'Q1 campaign' for Acme Coffee." > > > [accordion] unarchive_prompt > > > > Restores previously archived prompts so they resume running. > > > > **Example prompts** > > > > * "Restore the prompts I archived last month for Acme Coffee." > > * "Unarchive all prompts in the 'seasonal' tag so they start running again." > > ## Stages > > Read and reassign the customer-journey stage (Awareness, Consideration, Conversion, Loyalty, or a brand's own customized set) that prompts are classified into. > > > [accordion] list_prompt_stages > > > > Lists the brand's active customer-journey stages — id, name, description, and display order — which may differ from the default set if the brand has renamed or added stages. Use the returned ids/names with `update_stage_on_prompts` or the `stage_id` filter on `list_prompt_templates`. > > > > **Example prompts** > > > > * "What funnel stages do we have configured for Acme Coffee?" > > * "List our journey stages in display order." > > > [accordion] update_stage_on_prompts > > > > Assigns, changes, or clears the customer-journey stage on a batch of prompts in one call — pass `stage_id` or `stage_name` (or `stage_id=-1` to clear it). This marks the stage as manually assigned, so Scrunch's automatic classifier stops overwriting it going forward. That's one-way: clearing a manual stage later does not hand the prompt back to the classifier. > > > > **Example prompts** > > > > * "Move prompts #482 and #491 to the Conversion stage." > > * "Clear the stage on every prompt in the 'draft' tag." > > ## Topics > > Manage the topic taxonomy prompts are classified against — a closed, managed list, unlike the free-form tags below. > > > [accordion] list_prompt_topics > > > > Lists the brand's prompt topics (id, name) along with how many active or paused prompts carry each one. Use the ids/names with `add_topics_to_prompts`, `remove_topics_from_prompts`, or the `topic_ids` filter on `list_prompt_templates`. This list is the ceiling of what you can assign — topics are never created on the fly by the tools below. > > > > **Example prompts** > > > > * "What topics do we have configured for Acme Coffee, and how many prompts use each?" > > * "Is there already a topic for 'sustainability,' or does one need to be created first?" > > > [accordion] add_topics_to_prompts > > > > Adds one or more existing topics to a batch of prompts — additive only, a prompt's existing topics are preserved, and one that already has a given topic is silently skipped. Topics can be given as ids or names (case-insensitive); an unrecognized topic fails the whole call with the valid list rather than creating one. Pass the complete set of prompt ids you matched, not a hand-filtered subset — since already-labeled prompts are simply skipped, there's no cost to over-including. > > > > **Example prompts** > > > > * "Add the 'sustainability' and 'pricing' topics to every prompt tagged 'Q2 campaign'." > > * "Tag prompts #482 and #491 with the 'shipping' topic." > > > [accordion] remove_topics_from_prompts > > > > Removes one or more topics from a batch of prompts. Prompts that don't carry a given topic are silently ignored, and their other topics are unaffected. Removing a topic from prompts never deletes the topic itself from the brand's taxonomy. > > > > **Example prompts** > > > > * "Remove the 'seasonal' topic from every prompt now that the campaign's over." > > * "Take the 'draft' topic off prompts #482 and #491." > > ## Tags > > Read, add, and remove the tags attached to prompts so you can slice metrics by funnel stage, persona, campaign, or any custom dimension. Unlike topics, tags are free-form — `add_tag_to_prompts` creates a new tag on the fly if it doesn't already exist. > > > [accordion] get_tags > > > > Returns all tags currently configured for a brand. > > > > **Example prompts** > > > > * "What tags do we use for Acme Coffee?" > > * "Show me the full tag list across all our brands." > > > [accordion] add_tag_to_prompts > > > > Adds a single tag to a list of prompts (up to 500 at a time). Existing tags are preserved — this only appends, never replaces. The tag is created for the brand if it doesn't already exist, and prompts that already have it are skipped. > > > > **Example prompts** > > > > * "Tag prompts #482 and #483 with 'mobile'." > > * "Add the 'evergreen' tag to every prompt in the awareness stage." > > > [accordion] remove_tag_from_prompts > > > > Removes a single tag from a list of prompts. Prompts that don't have the tag are ignored, and other tags on each prompt are unaffected. > > > > **Example prompts** > > > > * "Remove the 'Q1 campaign' tag from prompts #482 and #483." > > * "Untag 'draft' from all the prompts I created yesterday." > [tab] Configure > > Set up and maintain what Scrunch tracks for each brand — the brands themselves, their competitors, and the personas you slice metrics by. > > ## Brands > > Look up and manage the brands tracked in your Scrunch organization. > > > [accordion] list_brands > > > > Lists all brands accessible within the authenticated organization, including name, website, status, and configuration details. > > > > **Example prompts** > > > > * "Show me all the brands I have access to in Scrunch." > > * "Which brands in our org have the most prompts configured?" > > > [accordion] create_brand > > > > Creates a new brand within the organization. Name, website, and status are required. > > > > **Example prompts** > > > > * "Create a new Scrunch brand for Acme Coffee, website acmecoffee.com." > > * "Set up a new brand for our UK subsidiary — name is Acme Coffee UK, website acmecoffee.co.uk." > > > [accordion] update_brand > > > > Updates an existing brand's name, alternative names, websites, geo, or case-sensitivity settings. > > > > **Example prompts** > > > > * "Add 'Acme Coffee Co.' as an alternative name for the Acme Coffee brand." > > * "Switch the geo for our Acme brand from US to UK." > > ## Competitors > > Manage the competitors tracked alongside each brand. > > > [accordion] list_competitors > > > > Lists all competitors being tracked for a specific brand, including their alternative names and websites. > > > > **Example prompts** > > > > * "Who are we tracking as competitors for Acme Coffee?" > > * "List the competitors for all our brands." > > > [accordion] create_competitor > > > > Adds a new competitor to a brand, with an optional list of alternative names and websites. > > > > **Example prompts** > > > > * "Add Blue Bottle as a competitor for Acme Coffee with website bluebottlecoffee.com." > > * "Start tracking Stumptown Coffee as a competitor — add their main site and their DTC site." > > > [accordion] update_competitor > > > > Updates an existing competitor's name, alternative names, or websites. > > > > **Example prompts** > > > > * "Add bluebottle.com as an alternative website for the Blue Bottle competitor." > > * "Rename the competitor 'Blue Bottle' to 'Blue Bottle Coffee' for Acme Coffee." > > > [accordion] create_competitors > > > > Creates several competitors in one call — the preferred way to add competitors via MCP, and fine for a single one too. Each item succeeds or fails independently, so one bad entry never sinks the batch. Per-item results come back as `created`, `already_exists` (a competitor with that name is already active, and its existing ID is returned), or `failed` (invalid URL, a website already claimed by another competitor, or a blocked name). > > > > **Example prompts** > > > > * "Add Blue Bottle, Stumptown, and Intelligentsia as competitors." > > * "Set up these 12 competitors for the new brand from this list." > > > [accordion] archive_competitor > > > > Soft-deletes a competitor from a brand's tracked list. History is preserved; the competitor just stops appearing in new data. > > > > **Example prompts** > > > > * "Stop tracking Blue Bottle as a competitor for Acme Coffee." > > * "Remove the three competitors we added last year that are no longer relevant." > > ## Personas > > Manage the personas tracked alongside each brand. Personas represent distinct customer segments (for example, "first-time buyers" or "enterprise IT admins") and can be attached to prompts so you can slice metrics by audience. > > > [accordion] list_personas > > > > Lists all personas configured for a brand, including their names and descriptions. > > > > **Example prompts** > > > > * "What personas do we have for Acme Coffee?" > > * "List the personas across all our brands." > > > [accordion] create_persona > > > > Creates a new persona on a brand. Requires a name and description. > > > > **Example prompts** > > > > * "Create a persona called 'Office manager' for Acme Coffee — someone responsible for stocking the office kitchen." > > * "Add a 'Home barista' persona for Acme Coffee focused on enthusiasts who grind their own beans." > > > [accordion] archive_persona > > > > Soft-deletes a persona from a brand. Historical data is preserved; the persona just stops appearing in new prompts and filters. > > > > **Example prompts** > > > > * "Archive the 'Q1 test' persona on Acme Coffee." > > * "Remove the personas we added during the pilot — they're no longer used." > > > [accordion] update_persona_on_prompts > > > > Assigns, changes, or removes the persona on a batch of prompts in one call. Pass a persona ID to attach it, or omit the persona to clear it. > > > > **Example prompts** > > > > * "Assign the 'Office manager' persona to all prompts tagged 'workplace' for Acme Coffee." > > * "Clear the persona on prompts #482, #491, and #503 — they should be persona-agnostic." > > ## Sub-brands > > Sub-brands are the product lines, series, and SKUs beneath a brand — yours or a competitor's. Tracking them separately lets you see whether AI assistants recommend a specific product rather than just the parent brand. Names are unique across the whole brand, so your own sub-brand and a competitor's can't share one. > > > [accordion] list_sub_brands > > > > Lists the brand's own sub-brands, including their tier. > > > > **Example prompts** > > > > * "What sub-brands do we track for Acme Coffee?" > > * "List our product lines and their tiers." > > > [accordion] create_sub_brands > > > > Creates one or more of the brand's own sub-brands. `tier` is optional and defaults to product line. Each item is processed independently, returning `created`, `already_exists`, `failed`, or `quota_exceeded`. A `quota_exceeded` result means your plan limit was reached — the remaining items are not created, and retrying them won't help. > > > > **Example prompts** > > > > * "Add Cold Brew, Espresso Roast, and Single Origin as sub-brands of Acme Coffee." > > * "Set up our four product lines from this spreadsheet." > > > [accordion] list_all_competitor_sub_brands > > > > Lists the sub-brands tracked across all of the brand's competitors, so you can see how deep competitive coverage goes in one call. > > > > **Example prompts** > > > > * "What competitor product lines are we tracking?" > > * "Which competitors have sub-brands configured and which don't?" > > > [accordion] create_competitor_sub_brands > > > > Creates sub-brands under a competitor. Every item needs the parent competitor's ID, which your assistant looks up first. Same per-item statuses and plan-limit behavior as `create_sub_brands`. > > > > **Example prompts** > > > > * "Add Blue Bottle's three main coffee lines as sub-brands." > > * "Track Stumptown's Hair Bender and Holler Mountain blends." > [tab] Agent traffic > > Bring AI bot crawl logs into Scrunch, or pull them out for analysis elsewhere. Useful for understanding how often GPTBot, ClaudeBot, PerplexityBot, and others are crawling your site. > > > [accordion] import_agent_traffic > > > > Ingests agent traffic logs from a CSV. Required columns: `domain`, `user_agent`, `url`, `path`, `method`, `status_code`, `timestamp`. Bot classification happens automatically on import. > > > > **Example prompts** > > > > * "Import this week's bot traffic CSV for acmecoffee.com." > > * "Load the server logs I just exported — here's the CSV." > > > [accordion] export_agent_traffic > > > > Exports agent traffic data as a CSV. Filterable by date range, site, path, and aggregation level (day or week). > > > > **Example prompts** > > > > * "Export the last 30 days of GPTBot traffic to acmecoffee.com." > > * "Give me a weekly summary of all AI bot activity on our site in Q1." > [tab] Keyword volume > > Estimate how often people ask AI assistants about your keywords: weekly US AI prompt volume, Demand Score and Commercial Intent for a list of up to 200 keywords. A list runs in the background, so your assistant starts it and checks back until it's done. Each keyword that hasn't been estimated recently uses one of the brand's weekly lookups. > > > [accordion] start_keyword_list > > > > Starts estimating a list of up to 200 keywords for a brand and returns the list's id at once. Keywords past the brand's remaining weekly lookups are skipped rather than the whole list refused. A brand runs one list at a time. It changes data, so most assistants confirm with you before calling it. > > > > **Example prompts** > > > > * "Estimate AI search volume for these 40 keywords for our brand." > > * "How much demand is there in AI assistants for each keyword in this list?" > > > [accordion] get_keyword_list > > > > Returns a list's status and each finished keyword's weekly volume, Demand Score and Commercial Intent score. Without an id, it returns the brand's most recent list. Keywords come back in pages of up to 50, so your assistant reads a long list in a few calls. > > > > **Example prompts** > > > > * "Is my keyword list done yet? Show me the top 10 by weekly volume." > > * "Which keywords on my last list have the highest commercial intent?" > > > [accordion] cancel_keyword_list > > > > Stops a running list. Keywords not yet estimated are canceled and their weekly lookups are given back; finished keywords keep their results. It changes data, so most assistants confirm with you before calling it. > > > > **Example prompts** > > > > * "Cancel the keyword list that's running." > [tab] Help & docs > > Answer questions about how Scrunch works. Your assistant reaches for the Help Center first, then falls back to Scrunch's public web content — always citing its sources. > > > [accordion] list_scrunch_help_collections > > > > Lists every Scrunch Help Center collection and the articles inside each one. Your assistant uses this to find the article that best matches a support-style question (features, troubleshooting, onboarding, plan/billing UX), then reads it with `get_scrunch_help_article`. > > > > **Example prompts** > > > > * "How do I set up a new brand in Scrunch?" > > * "What's the difference between branded and non-branded prompts?" > > > [accordion] get_scrunch_help_article > > > > Fetches the full body of a single Help Center article by ID — discovered via `list_scrunch_help_collections`. The assistant quotes or summarizes the article and cites its URL under a `Sources:` section. > > > > **Example prompts** > > > > * "Walk me through configuring competitors, and cite the help docs." > > * "Explain how funnel stages work, with a link to the article." > > > [accordion] search_scrunch_docs > > > > Searches the Scrunch developer documentation at `developers.scrunch.com` — API endpoints, authentication, SDK and curl examples, webhooks, integrations, and MCP setup. This is the one to reach for on developer and integration questions; metric definitions come from `get_metric_glossary` instead, which is more precise than docs prose. Returns snippets with page URLs, which your assistant then reads in full with `fetch_scrunch_url`. > > > > **Example prompts** > > > > * "How do I pull presence metrics through the REST API?" > > * "What's the curl example for authenticating against the Scrunch API?" > > * "How do I set up the Looker Studio connector?" > > > [accordion] fetch_scrunch_url > > > > Fetches a Scrunch-owned web page and returns its main content as markdown. Used when the Help Center doesn't cover a question and the answer lives in Scrunch's public content — product and feature pages on `scrunchai.com`, or REST/SDK reference on `developers.scrunch.com`. Only `scrunch.com`, `scrunchai.com`, and `developers.scrunch.com` (and their subdomains) are allowed. > > > > **Example prompts** > > > > * "Summarize the Agent Experience Platform product page." > > * "What do the developer docs say about API authentication?" > [tab] Utility > > Lightweight helpers your assistant uses automatically behind the scenes. > > > [accordion] get_caller_identity > > > > Returns the signed-in user's email, basic profile, and accessible brands. Your assistant calls this to determine which brands you have access to without asking you to look up a brand ID. > > > > **Example prompts** > > > > * "What brands do I have access to in Scrunch?" > > * "Which org am I connected to right now?" > > > [accordion] get_current_date > > > > Returns the server's current date in UTC. Your assistant uses this to anchor relative date phrases like "the last 30 days" or "this quarter" before constructing analytics queries. You don't need to call this directly. # Agent Traffic to a Spreadsheet Dashboard Source: https://developers.scrunch.com/mcp/workflows/agent-traffic-to-spreadsheet Export Scrunch's AI bot crawl data as CSV and turn it into a pivoted, chartable spreadsheet showing GPTBot, ClaudeBot, and PerplexityBot activity over time. `export_agent_traffic` gives you a CSV of raw crawl events — every hit from GPTBot, ClaudeBot, PerplexityBot, and other AI crawlers, with a timestamp, path, and status code. That's exactly what you want for a dashboard and exactly what you don't want to read row by row. This workflow has Claude do the export and the pivoting in one pass, so you land on a chart, not a CSV. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Exporting the agent traffic CSV | > | Google Sheets MCP or Excel MCP | Required (choose one) | Building the pivoted, chartable workbook | *** > [tab] Google Sheets > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [site domain] in Scrunch, export the last [30/60/90] days of agent traffic and turn it into a Google Sheets dashboard. > > Step 1 — Export the data: > Export agent traffic for [site domain] from [start date] to [end date], aggregated by day. > > Step 2 — Build the raw data tab: > Create a new Google Sheet called "[site domain] Agent Traffic — [month/year]". Add a "Raw Export" tab and load the exported rows: date, bot name, path, hit count. > > Step 3 — Build the pivot: > On a new "By Bot" tab, pivot the raw data into: one row per date, one column per bot (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, and any others present), with hit count as the value. Add a Total column. > > Step 4 — Chart it: > Create a stacked area chart on a "Chart" tab plotting hit count over date, broken out by bot, using the "By Bot" tab as the source. > > Step 5 — Summarize: > Which bot crawls [site domain] most? Is total crawl volume trending up or down over the period? Are there any days with an unusual spike or drop worth flagging? > ``` > > **What you get:** A three-tab spreadsheet — raw export, a per-bot pivot, and a stacked area chart — that turns a flat CSV into something you can actually read crawl trends off of at a glance. > [tab] Excel > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [site domain] in Scrunch, export the last [30/60/90] days of agent traffic and turn it into an Excel dashboard. > > Step 1 — Export the data: > Export agent traffic for [site domain] from [start date] to [end date], aggregated by day. > > Step 2 — Build the raw data sheet: > Create a new workbook called "[site domain] Agent Traffic — [month/year]". Add a "Raw Export" worksheet and load the exported rows: date, bot name, path, hit count. > > Step 3 — Build the pivot: > On a new "By Bot" worksheet, pivot the raw data into: one row per date, one column per bot (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, and any others present), with hit count as the value. Add a Total column. > > Step 4 — Chart it: > Create a stacked area chart on its own worksheet plotting hit count over date, broken out by bot, using the "By Bot" sheet as the source. > > Step 5 — Summarize: > Which bot crawls [site domain] most? Is total crawl volume trending up or down over the period? Are there any days with an unusual spike or drop worth flagging? > ``` > > **What you get:** A three-sheet workbook — raw export, a per-bot pivot, and a stacked area chart — that turns a flat CSV into something you can actually read crawl trends off of at a glance. *** ## Tips > [accordion] Correlating crawl volume with presence gains > > If a bot's crawl volume to a specific path jumped recently, check that page's citation rate in Scrunch for the same window — a crawl spike followed by a citation increase is a strong signal that the crawl directly fed a retrieval or indexing update. > [accordion] Filtering to specific paths > > Add "filtered to paths starting with \[/blog/ or /docs/]" to Step 1 if you only care about crawl activity on a specific site section rather than the whole domain. > [accordion] Spotting bots that aren't crawling you at all > > If a bot you expect to see (e.g. PerplexityBot) shows zero or near-zero hits across the whole period, that's worth investigating on its own — check robots.txt isn't blocking it and that the relevant pages are reachable without JavaScript rendering. > [accordion] Re-running this monthly > > Keep the same workbook and ask Claude to append the new month's export as additional rows on "Raw Export" rather than creating a new file each time — the pivot and chart will pick up the extended range automatically if they're built off the full sheet rather than a fixed row range. *** > [card] [Measure AI Visibility's Impact on Traffic](/mcp/workflows/ai-visibility-traffic-impact) > > Pair crawl activity with Google Analytics to see whether crawl attention is turning into referral traffic. > [card] [Which Cited Pages Actually Convert](/mcp/workflows/landing-page-citation-impact) > > Go one step further and check whether the pages getting crawled are the same ones driving citations and conversions. # Measure AI Visibility's Impact on Traffic Source: https://developers.scrunch.com/mcp/workflows/ai-visibility-traffic-impact Pair Google Analytics with Scrunch after lifting AI presence on a topic to confirm whether traffic followed and build the ROI case for AI visibility work. Improving your AI visibility is the work. Proving it drove results is what gets the next round of budget. This workflow connects Scrunch presence improvements to Google Analytics traffic data, so you can show exactly which pages got more traffic after they started getting cited by AI engines. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | AI visibility metrics before and after content changes | > | Google Analytics MCP | Recommended | Traffic data to correlate with AI visibility improvements | > > No Google Analytics MCP? Use the **Scrunch only** tab to pull the visibility side of the story — then compare to GA manually. *** > [tab] Google Analytics + Scrunch > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name], measure whether our AI visibility improvements have driven traffic growth. > > Step 1 — Pull before/after AI visibility from Scrunch: > Get presence metrics for [brand name] for two periods: > - Before period: [start date] to [end date] > - After period: [start date] to [end date] > > For each period, show: overall presence rate, presence rate per tag, and citation rate to [brand domain] per tag. Identify the tags where presence improved the most — these are the topics we'll cross-reference against traffic. > > Step 2 — Pull corresponding traffic data from Google Analytics: > For the same two date ranges, get: > - Organic traffic to [specific pages we optimized or created] — sessions and users, before vs. after > - Overall organic traffic to [domain] — any meaningful change in the period? > - Direct traffic — did brand awareness lift alongside AI visibility? > - Referral traffic from AI sources (Perplexity, ChatGPT, etc.) — are AI engines showing up as referrers yet? > > Step 3 — Find the correlation: > For each page or topic where Scrunch shows improved AI presence: > - Did organic traffic to that page increase in the same window? > - What's the % change in traffic vs. the % change in AI presence rate? > - Are there topics where AI visibility improved but traffic hasn't followed yet? (May just need more time) > - Any traffic gains that don't correlate with AI visibility changes? (Worth flagging) > > Step 4 — Write the impact summary: > Summarize the connection between AI visibility improvements and traffic outcomes. Be specific: which pages moved, by how much, over what timeframe. Flag anything that looks like a lagging indicator (visibility up, traffic not yet) and anything that looks like an outlier. > ``` > > **What you get:** A clear before/after story connecting AI visibility work to traffic outcomes — specific enough to present to a client or leadership team as evidence that Scrunch-driven content improvements are working. > [tab] Scrunch only > > No GA connected? This pulls the visibility side of the story. You can compare it against your GA data manually. > > ```text theme={null} > For [brand name] in Scrunch, give me a before/after comparison of AI visibility for topics where we've published or optimized content. > > Compare these two periods: > - Before: [start date] to [end date] > - After: [start date] to [end date] > > For each period, show: > 1. Overall presence rate and the change > 2. Presence rate per tag — which topics improved the most? > 3. Citation rate to [brand domain] per tag — are more citations pointing to our pages? > 4. For the tags that improved most: which specific prompts are now showing brand_present = true that weren't before? > > Summarize: what moved, by how much, and which pages are now being cited that weren't previously. I'll cross-reference this against Google Analytics traffic data manually. > ``` *** ## Tips > [accordion] How long before traffic follows AI visibility > > AI citation improvements typically take 30–90 days to show up in traffic data, depending on how frequently AI engines refresh their training or retrieval indexes. Run this workflow at the 30-day mark to check for early signals, then again at 60 and 90 days for a clearer picture. Don't write off a page because it hasn't moved in the first month. > [accordion] What counts as a meaningful correlation > > You're looking for directional evidence, not statistical proof. If a page's AI presence went from 10% to 45% and organic traffic grew 30% in the same period, that's a meaningful signal — even if you can't isolate AI as the sole cause. Be honest about confounding factors (seasonality, other content changes) when presenting the data. > [accordion] AI referral traffic in Google Analytics > > Some AI engines pass referral data — Perplexity in particular shows up in GA referral reports. ChatGPT Browse traffic sometimes appears as well. Look for these as direct signals in your referral report. Low numbers are normal — this channel is still early. The trend matters more than the absolute volume. > [accordion] Building an ongoing measurement dashboard > > Run this workflow monthly and save the output to Notion or Google Docs using the Monthly Client Report workflow. After 3–4 months you'll have a longitudinal dataset showing how AI visibility changes and traffic outcomes move together over time — much more compelling than a single before/after snapshot. *** > [card] [Build an AI Content Brief from Keyword Rankings](/mcp/workflows/keyword-rankings-to-ai-brief) > > Start here before creating content — combine SEO keyword data with Scrunch gaps to prioritize what to build. > [card] [Monthly Client Report](/mcp/workflows/monthly-client-report) > > Roll this measurement into a full monthly report with competitive context and recommendations. # Bulk Prompt Import from a Spreadsheet Source: https://developers.scrunch.com/mcp/workflows/bulk-prompt-import-from-sheets Read a spreadsheet of seed queries, tags, and personas you already have and bulk-create them as tracked Scrunch prompts in one conversation. Most teams don't start from zero — there's already a spreadsheet somewhere with a curated list of queries a client cares about, or one inherited from a previous tool. This workflow reads that spreadsheet directly and creates every row as a tracked Scrunch prompt, instead of re-typing the list one by one. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Google Sheets MCP or Excel MCP | Required (choose one) | Reading the source list of queries | > | Scrunch MCP | Required | Bulk-creating prompts, tags, and personas | *** > [tab] Google Sheets > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, bulk-import the prompt list from [spreadsheet name or URL]. > > Step 1 — Read the source list: > Open [spreadsheet name or URL] and read the [sheet/tab name] tab. Expect columns for: query text, tag (optional), persona (optional), platform (optional). Show me the first 10 rows so I can confirm the column mapping is right before continuing. > > Step 2 — Check for duplicates: > List existing prompt variants for [brand name]. Flag any rows from Step 1 that closely match a prompt that's already tracked, so we don't create duplicates. > > Step 3 — Create the new prompts: > For every non-duplicate row, create a Scrunch prompt using the query text. If a tag column has a value, apply that tag (creating it first if it doesn't exist). If a persona column has a value and that persona exists on this brand, assign it. > > Step 4 — Confirm: > Summarize: how many prompts were created, how many were skipped as duplicates, and how many tags were newly created versus reused. > ``` > > **What you get:** Every row in the spreadsheet turned into a tracked Scrunch prompt with its tags and persona already applied — a full prompt library migrated from a spreadsheet in one pass instead of hundreds of individual clicks. > [tab] Excel > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, bulk-import the prompt list from [workbook name or path]. > > Step 1 — Read the source list: > Open [workbook name or path] and read the [worksheet name] sheet. Expect columns for: query text, tag (optional), persona (optional), platform (optional). Show me the first 10 rows so I can confirm the column mapping is right before continuing. > > Step 2 — Check for duplicates: > List existing prompt variants for [brand name]. Flag any rows from Step 1 that closely match a prompt that's already tracked, so we don't create duplicates. > > Step 3 — Create the new prompts: > For every non-duplicate row, create a Scrunch prompt using the query text. If a tag column has a value, apply that tag (creating it first if it doesn't exist). If a persona column has a value and that persona exists on this brand, assign it. > > Step 4 — Confirm: > Summarize: how many prompts were created, how many were skipped as duplicates, and how many tags were newly created versus reused. > ``` > > **What you get:** Every row in the workbook turned into a tracked Scrunch prompt with its tags and persona already applied — a full prompt library migrated from a spreadsheet in one pass instead of hundreds of individual clicks. *** ## Tips > [accordion] Confirming the column mapping first > > Step 1 deliberately stops to show you a preview before creating anything — spreadsheets inherited from another tool or another teammate don't always have consistent column names, so it's worth a quick sanity check before hundreds of prompts get created from a misread column. > [accordion] Large imports — batch it > > For lists longer than a few hundred rows, ask Claude to process and confirm in batches of 100 rather than all at once — it's easier to catch and fix a mapping error early than to discover it after everything's already been created. > [accordion] No tag or persona columns yet? > > This workflow works fine with just a query column — tags and personas are optional. You can always run the Configuration & Maintenance prompts afterward to apply tags in bulk once everything's imported. > [accordion] Migrating a full setup, not just prompts > > If you're moving brands, competitors, and personas over as well — not just the prompt list — use the Switch from Another AI Visibility Tool workflow instead; it covers the full migration in one pass. *** > [card] [Switch from Another AI Visibility Tool in One Conversation](/mcp/workflows/switch-from-another-tool) > > For a full account migration, not just the prompt list. > [card] [New Brand Live in One Conversation](/mcp/workflows/new-brand-live) > > Pair this with brand and competitor setup when onboarding from scratch. # Citation Wins Tied to Pipeline Source: https://developers.scrunch.com/mcp/workflows/citation-wins-to-pipeline Match newly-won AI citations and prompt visibility against your CRM's open deals to show which AI visibility gains are touching active revenue. "Our AI visibility improved" is a metric. "Our AI visibility improved on the exact topic three open deals are researching" is a business case. This workflow cross-references Scrunch's newest wins against your CRM's pipeline so you can show, not just say, that the work is connected to revenue. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Identifying newly-won prompts and citations | > | HubSpot MCP or Salesforce MCP | Required (choose one) | Matching wins against open deals and logging the connection | *** > [tab] HubSpot > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find recent AI visibility wins and check whether they touch any open HubSpot deals. > > Step 1 — Find the wins: > Pull prompt variants filtered to brand_present = true for the last [14/30] days. Cross-reference against citation metrics to find prompts where [brand name]'s own domain is now being cited on a topic it wasn't before. List the specific prompts, their tags/topics, and the platforms involved. > > Step 2 — Match against pipeline: > For each topic area from Step 1, search open HubSpot deals for company names or deal notes that mention that topic or a closely related keyword. > > Step 3 — Log the connection: > For any deal that matches, add a note to the deal: "AI visibility update: [brand name] is now appearing in [platform] responses for '[topic]' as of [date]. Citation: [cited URL]. Relevant if this topic comes up in the sales conversation." > > Step 4 — Summarize: > List every deal that got a note, its stage and amount, and the specific visibility win tied to it. This is the evidence for "AI visibility work is touching open pipeline." > ``` > > **What you get:** A short list of open deals with a dated, sourced note showing exactly which AI visibility win is relevant to that conversation — real evidence to bring into a pipeline review or a case for continued investment. > [tab] Salesforce > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find recent AI visibility wins and check whether they touch any open Salesforce opportunities. > > Step 1 — Find the wins: > Pull prompt variants filtered to brand_present = true for the last [14/30] days. Cross-reference against citation metrics to find prompts where [brand name]'s own domain is now being cited on a topic it wasn't before. List the specific prompts, their tags/topics, and the platforms involved. > > Step 2 — Match against pipeline: > For each topic area from Step 1, search open Salesforce opportunities for account names or opportunity notes that mention that topic or a closely related keyword. > > Step 3 — Log the connection: > For any opportunity that matches, add an activity note: "AI visibility update: [brand name] is now appearing in [platform] responses for '[topic]' as of [date]. Citation: [cited URL]. Relevant if this topic comes up in the sales conversation." > > Step 4 — Summarize: > List every opportunity that got a note, its stage and amount, and the specific visibility win tied to it. This is the evidence for "AI visibility work is touching open pipeline." > ``` > > **What you get:** A short list of open opportunities with a dated, sourced note showing exactly which AI visibility win is relevant to that conversation — real evidence to bring into a pipeline review or a case for continued investment. *** ## Tips > [accordion] Matching is fuzzy — treat it as a starting list > > Topic-to-deal matching by keyword will surface some false positives, especially for common terms. Have Claude flag its confidence for each match ("strong: deal notes explicitly mention this topic" vs. "weak: same industry, no direct mention") and skim the weak ones before logging. > [accordion] Running this before a pipeline review > > Time this workflow a day or two before a sales or leadership pipeline review — the notes it adds are most useful when they're fresh enough to reference directly in the meeting. > [accordion] No topic-level fields in your CRM? > > If deals don't have structured topic tags, this relies on free-text matching against deal names and notes, which is noisier. Consider adding a simple "primary topic" custom field to deals going forward — it makes every future run of this workflow meaningfully more precise. > [accordion] Building this into the monthly report > > Include a "Pipeline Impact" section in the Monthly Client Report workflow that pulls directly from the deals this workflow flagged — it's one of the more concrete ROI arguments you can make to a client or to leadership. *** > [card] [Measure AI Visibility's Impact on Traffic](/mcp/workflows/ai-visibility-traffic-impact) > > Build the traffic side of the ROI case alongside the pipeline side. > [card] [Monthly Client Report, Built Automatically](/mcp/workflows/monthly-client-report) > > Roll pipeline-tied wins into the recurring report you already send. # Competitive Battlecard Generator Source: https://developers.scrunch.com/mcp/workflows/competitive-battlecard Build a per-competitor AI visibility battlecard covering wins, gaps, and talking points, saved to Notion or Google Docs for sales enablement. Sales teams already have product battlecards. This workflow builds the AI-visibility equivalent: where a specific competitor is winning the AI-answer conversation, where you're winning it, and what that means for how a rep should talk about the competitive landscape. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Competitive presence, position, and citation data | > | Notion MCP or Google Docs MCP | Required (choose one) | Saving the battlecard for sales to reference | *** > [tab] Notion > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, build a battlecard against [competitor name] and save it to Notion. > > Step 1 — Get the competitive picture: > Get the competitor ID for [competitor name]. Pull presence and position metrics for both [brand name] and [competitor name] over the last 30 days. > > Where they're winning: pull prompt variants filtered to competitor_present = [competitor name]'s ID and brand_present = false. Sort by observation count. Take the top 5. > > Where we're winning: pull prompt variants filtered to brand_present = true and competitor_present = false (for this competitor). Sort by observation count. Take the top 5. > > Check sentiment for both brands over the same period. > > Step 2 — Build the battlecard in Notion: > Create a page titled "[brand name] vs. [competitor name] — AI Visibility Battlecard" with: > - **Overall standing**: presence rate and rank for both brands > - **Where they're winning**: the 5 prompts from Step 1, with a one-line note on what to say if this comes up ("We're not currently cited on this specific question, but our strength is...") > - **Where we're winning**: the 5 prompts from Step 1, framed as proof points a rep can cite directly > - **Sentiment comparison**: how each brand is described when mentioned > - **Talking point summary**: 2-3 sentences a rep can use verbatim when a prospect brings up this competitor > > Step 3 — Confirm: > Give me the Notion page link and the one most important talking point from it. > ``` > > **What you get:** A Notion battlecard with concrete, sourced examples on both sides of the competitive comparison — not just "we're ahead" or "they're ahead," but the specific prompts and platforms behind that claim. > [tab] Google Docs > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, build a battlecard against [competitor name] and save it to Google Docs. > > Step 1 — Get the competitive picture: > Get the competitor ID for [competitor name]. Pull presence and position metrics for both [brand name] and [competitor name] over the last 30 days. > > Where they're winning: pull prompt variants filtered to competitor_present = [competitor name]'s ID and brand_present = false. Sort by observation count. Take the top 5. > > Where we're winning: pull prompt variants filtered to brand_present = true and competitor_present = false (for this competitor). Sort by observation count. Take the top 5. > > Check sentiment for both brands over the same period. > > Step 2 — Build the battlecard in Google Docs: > Create a document titled "[brand name] vs. [competitor name] — AI Visibility Battlecard" with: > - **Overall standing**: presence rate and rank for both brands > - **Where they're winning**: the 5 prompts from Step 1, with a one-line note on what to say if this comes up ("We're not currently cited on this specific question, but our strength is...") > - **Where we're winning**: the 5 prompts from Step 1, framed as proof points a rep can cite directly > - **Sentiment comparison**: how each brand is described when mentioned > - **Talking point summary**: 2-3 sentences a rep can use verbatim when a prospect brings up this competitor > > Step 3 — Confirm: > Give me the Google Docs link and the one most important talking point from it. > ``` > > **What you get:** A Google Docs battlecard with concrete, sourced examples on both sides of the competitive comparison — not just "we're ahead" or "they're ahead," but the specific prompts and platforms behind that claim. *** ## Tips > [accordion] Building a battlecard for every tracked competitor > > Run this once per competitor rather than trying to cover all of them in one document — a battlecard that's specific to one rival is more usable in the moment than a single sprawling document covering five. > [accordion] Keeping battlecards current > > Re-run this quarterly, or immediately after a Competitor Share of Voice report shows a meaningful rank change against that specific competitor. A battlecard with 6-month-old data is worse than no battlecard — reps will repeat stale claims. > [accordion] What to do when you're behind on every dimension > > If a competitor is winning on presence, position, and sentiment, don't force a "where we're winning" section that isn't true — say so directly and reframe the talking points around differentiation that isn't visibility-based (pricing, service, specific features) instead. > [accordion] Sharing this outside the sales team > > The same structure works as an input to the content team — "where they're winning" is effectively a prioritized content gap list specific to one competitor, and pairs directly with the Content Brief Handoff to Design workflow. *** > [card] [Competitor Share of Voice, Ranked](/mcp/workflows/competitor-share-of-voice) > > Run this first to decide which competitor deserves a battlecard. > [card] [Live Competitor Tracker Spreadsheet](/mcp/workflows/competitor-tracker-spreadsheet) > > Track the underlying numbers over time instead of a point-in-time battlecard. # Competitor Share of Voice, Ranked Source: https://developers.scrunch.com/mcp/workflows/competitor-share-of-voice Rank every tracked competitor by how often they appear in AI responses, find where they're displacing you, and surface the specific prompts to reclaim. Paste this in to get a full competitive ranking — who's ahead of you, which topic areas they're winning, and which prompts you should target to close the gap. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Competitive presence data, displacement analysis | > | Slack MCP | Optional | Posting the share of voice table to a team channel | *** > [tab] Full workflow (with Slack summary) > > ```text theme={null} > For [brand name] in Scrunch, run a full competitive share of voice analysis. > > Step 1 — Build the rankings: > 1. List all tracked competitors for [brand name] > 2. Get presence metrics for [brand name] and all competitors for the last 30 days, with competitors included in the results > 3. For each brand, calculate share of voice: their presence count as a percentage of total tracked variants > 4. Rank all brands — [brand name] and every competitor — by share of voice > > Step 2 — Map the displacement: > For each competitor that outranks [brand name]: > - Pull the specific prompts where that competitor appears and [brand name] does not > - Sort by observation count — these are the highest-stakes losses > - Identify which topic areas and funnel stages they're winning in > - Note whether their advantage is concentrated on specific AI platforms or consistent across all > > Step 3 — Find defensible positions: > Identify the prompts where [brand name] appears and the top 3 competitors do not. These are the positions to protect. > > Step 4 — Deliver the output: > Present: > - A ranked share of voice table (all brands, percentage, rank) > - For each competitor ahead of [brand name]: top 3 topic areas where they're winning + top 3 highest-observation prompts we should reclaim > - A one-paragraph competitive summary: are we the leader, challenger, or lagging? What is the single most impactful action to improve our rank? > > Then post this to [#channel-name] on Slack: > "📊 [brand name] AI Share of Voice — [date] > Our rank: [#X] of [total brands tracked] > Our share of voice: [X]% > [Competitor name] leads at [Y]% — biggest gap: [top topic area] > Recommended action: [one sentence]" > ``` > [tab] Scrunch only > > ```text theme={null} > For [brand name] in Scrunch, run a competitive share of voice analysis. > > 1. List all tracked competitors > 2. Get presence metrics for [brand name] and all competitors for the last 30 days — include competitors in the results > 3. Calculate share of voice for each: presence count as a percentage of total tracked variants > 4. Rank all brands by share of voice > > For each competitor that outranks [brand name]: > - What topics and funnel stages are they winning in? > - Which platform is their advantage most concentrated on? > - What are the top 3 specific prompts (by observation count) where they appear and we don't? > > End with a one-paragraph competitive summary and one recommended action. > ``` *** ## Tips > [accordion] Running a head-to-head against one competitor > > If you want to focus on a single competitor rather than all of them, use this prompt from the Prompt Library instead: "See Where a Competitor Is Beating You." It goes deeper on the displacement and topic breakdown for a specific brand. > [accordion] Adding this to your monthly report > > The share of voice table from Step 4 can be pasted directly into the Monthly Client Report workflow. Run competitive SOV first, then run the monthly report — Claude will have the competitive context in memory for the session. > [accordion] What to do with defensible positions > > The prompts where you appear and competitors don't are your moat. Note which pages and content types are driving those wins — those are your highest-performing AI assets to protect, expand, and use as a model for other content. *** > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Pair this with gap analysis to see which gaps are actually being won by competitors. > [card] [Monthly Client Report, Built Automatically](/mcp/workflows/monthly-client-report) > > Include this competitive data in a full monthly report saved to Notion. # Live Competitor Tracker Spreadsheet Source: https://developers.scrunch.com/mcp/workflows/competitor-tracker-spreadsheet Build a spreadsheet of share-of-voice by competitor that you re-run on a cadence to append each period's snapshot into a running trend tab. A one-time competitive report goes stale the day after you send it. This workflow builds a spreadsheet that's designed to be re-run — each time you paste the prompt back in, it appends a new row instead of starting over, so you end up with a real trend line instead of a pile of disconnected screenshots. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Competitive presence data and share-of-voice calculation | > | Google Sheets MCP or Excel MCP | Required (choose one) | Storing the running trend and rendering the chart | *** > [tab] Google Sheets > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, update my competitive share-of-voice tracker in Google Sheets. > > Step 1 — Pull this period's numbers: > List all tracked competitors for [brand name]. Get presence metrics for [brand name] and all competitors for the last 30 days, with competitors included in the results. Calculate each brand's share of voice: their presence count as a percentage of total tracked variants. > > Step 2 — Update the spreadsheet: > Open [spreadsheet name or URL]. If a tab called "SOV Trend" doesn't exist, create one with columns: Date, Brand, Share of Voice %, Rank. > > Append one row per brand for today's date — [brand name] plus every competitor — to the "SOV Trend" tab. Don't overwrite existing rows; this should be additive so the sheet builds a history over time. > > Step 3 — Refresh the chart: > If a line chart plotting Share of Voice % over Date, grouped by Brand, doesn't already exist on a "Chart" tab, create one. If it exists, confirm it's picking up the new rows automatically. > > Step 4 — Summarize what moved: > Compare today's rank and share of voice for [brand name] against the previous entry in the sheet (if any). Call out: did our rank change? Did any competitor pass us or fall behind? By how much? > ``` > > **What you get:** A living spreadsheet with one tab holding the full historical trend and a chart that updates itself as you add rows — re-run this weekly or monthly and watch the competitive picture accumulate instead of re-explaining it from scratch each time. > [tab] Excel > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, update my competitive share-of-voice tracker in Excel. > > Step 1 — Pull this period's numbers: > List all tracked competitors for [brand name]. Get presence metrics for [brand name] and all competitors for the last 30 days, with competitors included in the results. Calculate each brand's share of voice: their presence count as a percentage of total tracked variants. > > Step 2 — Update the workbook: > Open [workbook name or path]. If a worksheet called "SOV Trend" doesn't exist, create one with columns: Date, Brand, Share of Voice %, Rank. > > Append one row per brand for today's date — [brand name] plus every competitor — to the "SOV Trend" sheet. Don't overwrite existing rows; this should be additive so the workbook builds a history over time. > > Step 3 — Refresh the chart: > If a line chart plotting Share of Voice % over Date, grouped by Brand, doesn't already exist, create one on its own worksheet. If it exists, confirm the data range covers the newly added rows. > > Step 4 — Summarize what moved: > Compare today's rank and share of voice for [brand name] against the previous entry in the workbook (if any). Call out: did our rank change? Did any competitor pass us or fall behind? By how much? > ``` > > **What you get:** A living workbook with one sheet holding the full historical trend and a chart that updates as you add rows — re-run this weekly or monthly and watch the competitive picture accumulate instead of re-explaining it from scratch each time. *** ## Tips > [accordion] How often to re-run this > > Weekly is enough to catch real movement without adding noise — share of voice rarely swings meaningfully day to day. Monthly works fine for a slower-moving competitive set. Pick a cadence and stick to it; consistent spacing between rows makes the trend line easier to read than irregular snapshots. > [accordion] Starting the tracker for the first time > > On the very first run, the sheet won't have a previous entry to compare against — that's expected. Claude will just populate today's row and skip Step 4's comparison. The trend becomes useful starting with the second run. > [accordion] Tracking more than share of voice > > Extend Step 1 to also pull sentiment or citation share per brand, and add matching columns to the tracker tab. The same append-only pattern works for any metric — the key is keeping Date and Brand as the two columns every new metric joins against. > [accordion] Sharing the tracker without giving edit access > > Once the trend tab has a few weeks of history, ask Claude to pull the latest 8-12 rows and summarize them as a short written update — that's a safer thing to paste into a client email or Slack channel than sharing edit access to the live sheet. *** > [card] [Competitor Share of Voice, Ranked](/mcp/workflows/competitor-share-of-voice) > > Run the full one-time analysis (displacement, defensible positions) before setting up the recurring tracker. > [card] [Competitive Battlecard Generator](/mcp/workflows/competitive-battlecard) > > Turn this same competitive data into sales-facing battlecards instead of a trend sheet. # Content Brief Handoff to Design Source: https://developers.scrunch.com/mcp/workflows/content-brief-to-design Turn a Scrunch visibility gap into a structured content brief and hand it to your design or content team as a FigJam board, ready to move into layout. The data on a visibility gap usually lives in Scrunch, but the people who design and lay out the content that fixes it live in Figma. This workflow bridges the two: it turns a gap into a structured brief and drops it directly into a FigJam board your design team already works in. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Identifying the gap and pulling supporting citation data | > | Figma MCP | Required | Creating the FigJam brief board | *** ```text theme={null} For [brand name] in Scrunch, turn our biggest content gap into a design-ready brief in FigJam. Step 1 — Find the gap and its context: Get all tags. For each tag, get presence metrics for the last 30 days and calculate the presence rate. Identify the tag with the lowest presence rate that has at least [10] observations. For that tag: - List the top 5 specific prompts where [brand name] is absent, sorted by observation count - Check citations for those prompts: which competitor or third-party domains are getting cited instead? - Note the funnel stage these prompts fall into (awareness, consideration, decision) Step 2 — Build the brief in FigJam: Create a new FigJam board called "[topic area] — Content Brief" with these sections, one per sticky-note cluster: - **The gap**: [brand name]'s current presence rate on this topic and why it matters - **What to answer**: the specific questions from the 5 prompts in Step 1, rewritten as headers a piece of content could directly address - **Who's winning it now**: the competitor or third-party sources currently cited, and what they're doing that seems to be working - **Funnel stage & tone**: whether this content should read as introductory (awareness) or comparative/decisive (consideration/decision), which affects layout and depth - **Success metric**: presence rate on this tag should improve within 30-60 days of publishing Step 3 — Confirm: Give me the FigJam board link and a one-line summary of what's on it. ``` **What you get:** A FigJam board with the gap, the specific questions to answer, the competitive context, and the tone/funnel guidance — everything a designer or content lead needs to start laying out the piece, without translating a data export themselves. *** ## Tips > [accordion] When the handoff is to a writer, not a designer > > If your content team writes first and designs later, use the Create Content That Gets AI Citations workflow instead — it's built for drafting the content itself rather than briefing a layout. > [accordion] Batching multiple gaps into one board > > Ask Claude to repeat Step 1 for the next 2-3 lowest-performing tags and add each as its own section on the same FigJam board, so design can see and prioritize across several briefs at once rather than one gap at a time. > [accordion] Keeping the brief lightweight > > Resist the urge to add every data point Scrunch can surface — a brief with 5 questions and one competitive callout gets used; a brief with 20 data points gets skimmed once and ignored. Keep Step 1 focused on the single tag with the clearest story. > [accordion] Closing the loop after publishing > > Once the content ships, use the Track Whether It Worked step from Create Content That Gets AI Citations to check whether the presence rate on this tag actually improved. *** > [card] [Create Content That Gets AI Citations](/mcp/workflows/create-content-for-citations) > > For teams that draft the content directly instead of handing off a design brief. > [card] [Stage Content Tasks for Review](/mcp/workflows/content-task-handoff) > > For handing the gap off as a tracked ticket instead of a FigJam brief. # Stage Content Tasks for Review Source: https://developers.scrunch.com/mcp/workflows/content-task-handoff MCP workflow that turns a Scrunch content gap into a fully-briefed Linear, Jira, GitHub, or Asana ticket for the teammate who owns publishing. Not everyone who monitors Scrunch has the permissions — or the bandwidth — to publish content themselves. This workflow closes that gap: pull the visibility data, have Claude draft a fully-contextualized task, and create it in your team's project management tool so the right person can pick it up. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Identifying the content gap and providing brief context | > | Linear / Jira / GitHub / Asana MCP | Required (choose one) | Creating the task for the content owner | > > Choose your project management tool in the tabs below. *** > [tab] Linear > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority content gap and create a task for the content team. > > Step 1 — Find the gap: > Get all tags. For each tag, pull presence metrics for the last 30 days and calculate the presence rate. Identify the tag with the lowest presence rate that has at least [10] observations. > > For that tag: > - List the 5 specific prompts where [brand name] is absent, sorted by observation count > - Check citations: what share is going to competitors vs. third parties vs. brand-owned? > - Is any tracked competitor consistently appearing in these prompts? Which one? > > Step 2 — Create a Linear issue in [team name]: > Title: "AI Visibility Gap: [topic area] — content needed" > > Description: > ## What Scrunch found > [Brand name] has [X]% presence on [topic] — one of our lowest-performing areas. AI engines are answering questions in this space but not citing our content. > > ## The specific prompts we're missing > [List the 5 prompts from Step 1 with observation counts] > > ## Who's winning instead > [Competitor name or third-party domain] appears in [X]% of these responses. > > ## What needs to happen > [New content / update to existing page] that directly answers these questions. See the Create Content for AI Citations workflow for how to structure it: https://developers.scrunch.com/mcp/workflows/create-content-for-citations > > ## Success metric > Track this tag in Scrunch after publishing — presence rate should increase within 30–60 days. > > Labels: ai-visibility, content > Priority: [High / Medium based on observation count] > Assignee: [name or email] > ``` > > **What you get:** A Linear issue with the full gap context already written — topic, missing prompts, competitor situation, and a clear brief for whoever picks it up. > [tab] Jira > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority content gap and create a task for the content team. > > Step 1 — Find the gap: > Get all tags. For each tag, pull presence metrics for the last 30 days and calculate the presence rate. Identify the tag with the lowest presence rate that has at least [10] observations. > > For that tag: > - List the 5 specific prompts where [brand name] is absent, sorted by observation count > - Check citations: what share is going to competitors vs. third parties vs. brand-owned? > - Is any tracked competitor consistently appearing in these prompts? Which one? > > Step 2 — Create a Jira issue in project [PROJECT-KEY]: > Issue type: Task > Summary: "AI Visibility Gap: [topic area] — content needed" > > Description (use Jira markup): > h2. What Scrunch found > [Brand name] has [X]% presence on [topic] — one of our lowest-performing areas. AI engines are answering questions in this space but not citing our content. > > h2. The specific prompts we're missing > [List the 5 prompts from Step 1 with observation counts] > > h2. Who's winning instead > [Competitor name or third-party domain] appears in [X]% of these responses. > > h2. What needs to happen > [New content / update to existing page] that directly answers these questions. See the Create Content for AI Citations workflow: https://developers.scrunch.com/mcp/workflows/create-content-for-citations > > h2. Success metric > Track this tag in Scrunch after publishing — presence rate should increase within 30–60 days. > > Labels: ai-visibility, content > Priority: [High / Medium based on observation count] > Assignee: [name or email] > ``` > > **What you get:** A Jira task with the full gap context already written — topic, missing prompts, competitor situation, and a clear brief for whoever picks it up. > [tab] GitHub Issues > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority content gap and create a GitHub issue for the content team. > > Step 1 — Find the gap: > Get all tags. For each tag, pull presence metrics for the last 30 days and calculate the presence rate. Identify the tag with the lowest presence rate that has at least [10] observations. > > For that tag: > - List the 5 specific prompts where [brand name] is absent, sorted by observation count > - Check citations: what share is going to competitors vs. third parties vs. brand-owned? > - Is any tracked competitor consistently appearing in these prompts? Which one? > > Step 2 — Create a GitHub issue in [owner/repo]: > Title: "AI Visibility Gap: [topic area] — content needed" > > Body: > ## What Scrunch found > [Brand name] has [X]% presence on [topic] — one of our lowest-performing areas. AI engines are answering questions in this space but not citing our content. > > ## The specific prompts we're missing > | Prompt | Observations | > |---|---| > [List the 5 prompts from Step 1] > > ## Who's winning instead > [Competitor name or third-party domain] appears in [X]% of these responses. > > ## What needs to happen > [New content / update to existing page] that directly answers these questions. See the [Create Content for AI Citations](https://developers.scrunch.com/mcp/workflows/create-content-for-citations) workflow for how to structure it. > > ## Success metric > Track this tag in Scrunch after publishing — presence rate should increase within 30–60 days. > > Labels: ai-visibility, content > Assignees: [username] > ``` > > **What you get:** A GitHub issue with the full gap context already written — topic, missing prompts, competitor situation, and a clear brief for whoever picks it up. > [tab] Asana > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority content gap and create a task for the content team. > > Step 1 — Find the gap: > Get all tags. For each tag, pull presence metrics for the last 30 days and calculate the presence rate. Identify the tag with the lowest presence rate that has at least [10] observations. > > For that tag: > - List the 5 specific prompts where [brand name] is absent, sorted by observation count > - Check citations: what share is going to competitors vs. third parties vs. brand-owned? > - Is any tracked competitor consistently appearing in these prompts? Which one? > > Step 2 — Create an Asana task in project [project name]: > Name: "AI Visibility Gap: [topic area] — content needed" > > Description: > What Scrunch found: > [Brand name] has [X]% presence on [topic] — one of our lowest-performing areas. AI engines are answering questions in this space but not citing our content. > > The specific prompts we're missing: > [List the 5 prompts from Step 1 with observation counts] > > Who's winning instead: > [Competitor name or third-party domain] appears in [X]% of these responses. > > What needs to happen: > [New content / update to existing page] that directly answers these questions. See the Create Content for AI Citations workflow: https://developers.scrunch.com/mcp/workflows/create-content-for-citations > > Success metric: > Track this tag in Scrunch after publishing — presence rate should increase within 30–60 days. > > Assignee: [name or email] > Due date: [date] > Tags: ai-visibility, content > ``` > > **What you get:** An Asana task with the full gap context already written — topic, missing prompts, competitor situation, and a clear brief for whoever picks it up. *** ## Tips > [accordion] Batching multiple gaps into one session > > After Step 1, ask: "Repeat this for the next 2 lowest-performing tags." You'll get 3 gap summaries. Then create a ticket for each using the same tab — one conversation, three tasks created and assigned. > [accordion] Linking back to Scrunch in the ticket > > Add this line to the ticket description: "Scrunch tag: \[tag name] — filter to this tag in the dashboard for the full data." Whoever picks up the task can open Scrunch directly to the relevant data without running the analysis again. > [accordion] When to create new content vs. update existing > > If Scrunch shows you're present sometimes but inconsistently (presence rate 10–40%), you likely need to update an existing page rather than create something new. Add this to Step 1: "Does \[brand name] have any presence in this tag at all, or is it zero? If partial, what's the presence rate?" Zero presence usually means missing content; partial presence usually means weak content. > [accordion] Tracking resolution back in Scrunch > > Once the content is published, add the URL to the ticket and check Scrunch in 30 days. Use the Track Whether It Worked step from the Create Content for AI Citations workflow to close the loop. *** > [card] [Create Content That Gets AI Citations](/mcp/workflows/create-content-for-citations) > > The workflow for whoever picks up the ticket — pull the brief from Scrunch, generate the content, publish through your CMS. > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Run a deeper gap analysis first and save it to Notion or Google Docs before creating tasks. # Create Content That Gets AI Citations Source: https://developers.scrunch.com/mcp/workflows/create-content-for-citations Use Scrunch citation gaps to identify what to write, generate content optimized for AI retrieval, and publish it through your CMS — all in one workflow. Most content strategies are built for search engines. This workflow builds content for AI engines. It starts with Scrunch data to find the exact questions AI is answering without citing your pages, generates content specifically structured to be cited, and publishes it directly through your CMS. The result: content targeted at the prompts where your competitors are getting cited and you aren't. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Identifying citation gaps and the specific prompts to target | > | CMS MCP | Recommended | Publishing the generated content directly | > | Brand style guide | Optional | Paste into the prompt or attach as context | > > Choose your CMS in the tabs below. Supported integrations: Sanity, WordPress, HubSpot, and any CMS with an MCP connector. No CMS connected? Use the **Generate only** tab to get the content in the chat and paste it yourself. *** > [tab] Sanity > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority citation gap and create AI-optimized content for it. > > Step 1 — Find the gap: > Get citation metrics for the last 30 days. Get all tags and calculate the citation rate from [brand domain] for each — variants with brand_present = true and a citation pointing to [brand domain] divided by total variants. Rank tags by citation rate lowest to highest. For the lowest-performing tag, list the prompts where brand_present = false, sorted by observation count. Note what sources are being cited instead. > > Step 2 — Get the brief: > Identify the single highest-priority topic: most prompts where we're absent + highest observation counts + clearest commercial relevance. > > Give me a content brief: > - The 5–8 specific questions this page should directly answer > - What the competing or cited content is doing that ours isn't > - The recommended format (article, comparison page, FAQ, landing page, etc.) > - What specific facts, figures, or claims would make this page more citable than what's currently appearing > > Step 3 — Write the content: > Write a [blog post / guide / comparison page / FAQ page] for [brand name] on the topic identified above. > > Structure it to be cited by AI engines: > - Open with a direct, concise answer to the primary question — 2–3 sentences an AI could extract and cite verbatim > - Use clear H2 and H3 headings that match how users phrase these questions in AI assistants > - Include specific, factual claims with numbers, dates, or rankings where possible — generic statements don't get cited > - Answer each of the specific questions from Step 2 directly and completely > - Avoid marketing language in the factual sections — AI cites descriptive, informational content > - Target length: [800–1,500 words] unless the topic warrants more depth > > [Optional: follow this brand style guide: paste guidelines here] > > Step 4 — Publish to Sanity: > Publish this content as a new Sanity document: > - Document type: [article / blog-post / page — match your schema] > - Title: [SEO-optimized title for the topic] > - Slug: [url-friendly-slug] > - Body: [the content generated above] > - SEO meta description: Write a 150-character meta description focused on the primary question this page answers > - Status: [draft / published] > - [Any other schema fields relevant to your Sanity setup] > ``` > > **What you get:** A new Sanity document, set to draft, ready for your review before publishing. The content is structured specifically to be extracted and cited by AI engines — direct answers up front, factual specificity throughout, headings that match real AI queries. > [tab] WordPress > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority citation gap and create AI-optimized content for it. > > Step 1 — Find the gap: > Get citation metrics for the last 30 days. Get all tags and calculate the citation rate from [brand domain] for each — variants with brand_present = true and a citation pointing to [brand domain] divided by total variants. Rank tags by citation rate lowest to highest. For the lowest-performing tag, list the prompts where brand_present = false, sorted by observation count. Note what sources are being cited instead. > > Step 2 — Get the brief: > Identify the single highest-priority topic: most prompts where we're absent + highest observation counts + clearest commercial relevance. > > Give me a content brief: > - The 5–8 specific questions this page should directly answer > - What the competing or cited content is doing that ours isn't > - The recommended format (article, comparison page, FAQ, landing page, etc.) > - What specific facts, figures, or claims would make this page more citable than what's currently appearing > > Step 3 — Write the content: > Write a [blog post / guide / comparison page / FAQ page] for [brand name] on the topic identified above. > > Structure it to be cited by AI engines: > - Open with a direct, concise answer to the primary question — 2–3 sentences an AI could extract and cite verbatim > - Use clear H2 and H3 headings that match how users phrase these questions in AI assistants > - Include specific, factual claims with numbers, dates, or rankings where possible — generic statements don't get cited > - Answer each of the specific questions from Step 2 directly and completely > - Avoid marketing language in the factual sections — AI cites descriptive, informational content > - Target length: [800–1,500 words] unless the topic warrants more depth > > [Optional: follow this brand style guide: paste guidelines here] > > Step 4 — Create a WordPress draft: > Create a new WordPress post with this content: > - Title: [SEO-optimized title] > - Content: [the generated article, formatted as WordPress blocks] > - Status: draft > - Category: [category name] > - Tags: [relevant tags] > - SEO meta description: [150-character description focused on the primary question] > > Set it as a draft so I can review before publishing. > ``` > > **What you get:** A WordPress draft ready for your review. The content is structured specifically to be extracted and cited by AI engines — direct answers up front, factual specificity throughout, headings that match real AI queries. > [tab] HubSpot > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority citation gap and create AI-optimized content for it. > > Step 1 — Find the gap: > Get citation metrics for the last 30 days. Get all tags and calculate the citation rate from [brand domain] for each — variants with brand_present = true and a citation pointing to [brand domain] divided by total variants. Rank tags by citation rate lowest to highest. For the lowest-performing tag, list the prompts where brand_present = false, sorted by observation count. Note what sources are being cited instead. > > Step 2 — Get the brief: > Identify the single highest-priority topic: most prompts where we're absent + highest observation counts + clearest commercial relevance. > > Give me a content brief: > - The 5–8 specific questions this page should directly answer > - What the competing or cited content is doing that ours isn't > - The recommended format (article, comparison page, FAQ, landing page, etc.) > - What specific facts, figures, or claims would make this page more citable than what's currently appearing > > Step 3 — Write the content: > Write a [blog post / guide / comparison page / FAQ page] for [brand name] on the topic identified above. > > Structure it to be cited by AI engines: > - Open with a direct, concise answer to the primary question — 2–3 sentences an AI could extract and cite verbatim > - Use clear H2 and H3 headings that match how users phrase these questions in AI assistants > - Include specific, factual claims with numbers, dates, or rankings where possible — generic statements don't get cited > - Answer each of the specific questions from Step 2 directly and completely > - Avoid marketing language in the factual sections — AI cites descriptive, informational content > - Target length: [800–1,500 words] unless the topic warrants more depth > > [Optional: follow this brand style guide: paste guidelines here] > > Step 4 — Create a HubSpot blog post: > Create a new HubSpot blog post: > - Title: [title] > - Body: [generated content] > - Meta description: [150-character description focused on the primary question] > - Campaign: [campaign name if applicable] > - Publish state: DRAFT > ``` > > **What you get:** A HubSpot blog draft ready for review. The content is structured specifically to be extracted and cited by AI engines — direct answers up front, factual specificity throughout, headings that match real AI queries. > [tab] Other CMS > > Works for Webflow, Ghost, Contentful, or any CMS with an MCP connector. Replace the bracketed values, then paste. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority citation gap and create AI-optimized content for it. > > Step 1 — Find the gap: > Get citation metrics for the last 30 days. Get all tags and calculate the citation rate from [brand domain] for each — variants with brand_present = true and a citation pointing to [brand domain] divided by total variants. Rank tags by citation rate lowest to highest. For the lowest-performing tag, list the prompts where brand_present = false, sorted by observation count. Note what sources are being cited instead. > > Step 2 — Get the brief: > Identify the single highest-priority topic: most prompts where we're absent + highest observation counts + clearest commercial relevance. > > Give me a content brief: > - The 5–8 specific questions this page should directly answer > - What the competing or cited content is doing that ours isn't > - The recommended format (article, comparison page, FAQ, landing page, etc.) > - What specific facts, figures, or claims would make this page more citable than what's currently appearing > > Step 3 — Write the content: > Write a [blog post / guide / comparison page / FAQ page] for [brand name] on the topic identified above. > > Structure it to be cited by AI engines: > - Open with a direct, concise answer to the primary question — 2–3 sentences an AI could extract and cite verbatim > - Use clear H2 and H3 headings that match how users phrase these questions in AI assistants > - Include specific, factual claims with numbers, dates, or rankings where possible — generic statements don't get cited > - Answer each of the specific questions from Step 2 directly and completely > - Avoid marketing language in the factual sections — AI cites descriptive, informational content > - Target length: [800–1,500 words] unless the topic warrants more depth > > [Optional: follow this brand style guide: paste guidelines here] > > Step 4 — Publish to [CMS name]: > Create a new [content type] in [CMS name] with: > - Title: [title] > - Body/Content: [the generated article] > - Meta description: Write a 150-character description focused on the primary question this page answers > - Status: draft > ``` > > **No MCP connector?** After Step 3, ask Claude to format the output as HTML or Markdown ready for copy-paste into your CMS editor instead. > [tab] Generate only > > No CMS connected? This tab gives you the full analysis and content in the chat — paste it wherever you need it. > > ```text theme={null} > For [brand name] in Scrunch, find the highest-priority citation gap and write AI-optimized content to fill it. > > Step 1 — Find the gap: > Get citation metrics for the last 30 days. Get all tags and calculate the citation rate from [brand domain] for each — variants with brand_present = true and a citation pointing to [brand domain] divided by total variants. Rank tags by citation rate lowest to highest. For the lowest-performing tag, list the prompts where brand_present = false, sorted by observation count. Note what sources are being cited instead. > > Step 2 — Get the brief: > Identify the single highest-priority topic: most prompts where we're absent + highest observation counts + clearest commercial relevance. > > Give me a content brief: > - The 5–8 specific questions this page should directly answer > - What the competing or cited content is doing that ours isn't > - The recommended format (article, comparison page, FAQ, landing page, etc.) > - What specific facts, figures, or claims would make this page more citable > > Step 3 — Write the content: > Write a [blog post / guide / comparison page / FAQ page] for [brand name] on the topic identified above. > > Structure it to be cited by AI engines: > - Open with a direct, concise answer to the primary question — 2–3 sentences an AI could extract and cite verbatim > - Use clear H2 and H3 headings that match how users phrase these questions in AI assistants > - Include specific, factual claims with numbers, dates, or rankings where possible > - Answer each of the specific questions from Step 2 directly and completely > - Avoid marketing language in the factual sections > - Target length: [800–1,500 words] unless the topic warrants more depth > > Format the final output as Markdown, ready to paste into any CMS or doc editor. > > [Optional: follow this brand style guide: paste guidelines here] > ``` *** ## Track whether it worked After publishing, save the URL and check back in Scrunch after 30–60 days. ```text theme={null} For [brand name] in Scrunch, check whether our new content at [published URL] is being cited. Pull citation metrics for the tag [topic tag]. Has the citation rate for [brand domain] improved compared to last month? Are the specific prompts from the gap analysis now showing brand_present = true? ``` This closes the loop: Scrunch identified the gap, content filled it, Scrunch confirms whether it worked. *** ## Tips > [accordion] What makes content AI-citable > > AI engines cite pages that **directly answer a specific question** with a clear, extractable statement. The most citable content has: a direct answer in the first paragraph, factual specificity (numbers, comparisons, rankings), question-matching headers, and no ambiguity about what the page is claiming. Generic "thought leadership" rarely gets cited — specific, opinionated, factual writing does. > [accordion] Updating existing pages vs. creating new ones > > If Scrunch shows that a topic is partially covered (you appear sometimes but not consistently), you may not need new content — you need to update an existing page. In Step 3, change the instruction to: "Rewrite and expand the \[existing page title] to more directly answer these specific questions from Scrunch. Focus on adding the citable, factual sections that are currently missing." > [accordion] Running this for multiple topic gaps at once > > After Step 2, ask Claude: "Repeat Step 2 for the next 3 lowest-performing tags and give me a prioritized brief for each." You'll get 4 content briefs in one session. Then run Step 3 for each in the same conversation or batch them into separate sessions. > [accordion] Including competitor analysis in the brief > > Add this to Step 2: "For the top 3 competitor or third-party URLs being cited in this topic gap, describe what those pages cover that ours don't. What specific angles, data points, or question-types do they address that we're missing?" This makes your content brief much sharper. > [accordion] Using your brand style guide > > Paste style guidelines directly into Step 3 after the main prompt. For a longer style guide (5,000+ words), attach it as a file or paste it in a prior message before running the workflow. *** > [card] [Build Your Prompt Library from SEO Keywords](/mcp/workflows/prompts-from-keywords) > > Make sure you're tracking the right prompts before creating content — use SEO keywords to find gaps in your Scrunch coverage. > [card] [Stage Content Tasks for Review](/mcp/workflows/content-task-handoff) > > Not the one who publishes? Create a briefed ticket in Linear, Jira, GitHub, or Asana for whoever does. # Executive Explorer Dashboard Source: https://developers.scrunch.com/mcp/workflows/executive-explorer-dashboard Assemble a saved Scrunch Explorer dashboard covering presence, position, sentiment, and citations in one conversation, and get a shareable link back. Skip the slide deck when a live, clickable view will do. This workflow has Claude assemble a multi-tile Explorer dashboard directly from a plain-English brief — no manual chart building required — and hand you back a link you can share or bookmark. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Notes | > | - | - | - | > | Scrunch MCP | Required | Uses `create_explorer_dashboard`, which writes a saved dashboard to your Scrunch organization | > > This workflow uses a write operation. Your AI agent will confirm the tile list before saving the dashboard. *** ```text theme={null} For [brand name] in Scrunch, build an executive Explorer dashboard covering the last [30/90] days. Step 1 — Propose the tiles: Put together a dashboard with 5-6 tiles mixing headline numbers and trend charts: 1. A card tile: current overall presence rate 2. A line chart: presence rate over time, with [top competitor] overlaid for comparison 3. A card tile: current share of voice rank among tracked competitors 4. A line chart: sentiment breakdown (positive/mixed/negative) over time 5. A bar chart: citations broken down by owner (brand, competitor, third-party) 6. A line chart: position (top/middle/bottom) over time Show me the proposed tile list before saving anything. Step 2 — Save it: Once I confirm, create the dashboard named "[brand name] Executive Overview — [month/year]" with those tiles and give me the link. Step 3 — Summarize: In 2-3 sentences, tell me what the dashboard shows at a glance right now — is the overall picture improving, flat, or declining? ``` **What you get:** A saved, shareable Explorer dashboard link plus a short plain-English read on what it currently shows — refresh the link any time rather than rebuilding a deck from scratch. *** ## Tips > [accordion] Building this for a client vs. for internal use > > For a client-facing dashboard, keep the tile count to 5-6 and favor card tiles for headline numbers — clients want a fast read, not a data exploration surface. For an internal team dashboard, add more granular breakdowns (per-platform, per-tag) since the audience is more likely to dig in. > [accordion] Updating an existing dashboard vs. creating a new one > > `create_explorer_dashboard` always creates a new saved dashboard rather than editing one in place. If you're refreshing a recurring dashboard, either keep using the same link (dashboards reflect live data automatically, so tiles update without a rebuild) or explicitly ask for a new dashboard only when the tile mix itself needs to change. > [accordion] Pairing this with generate_explorer_chart > > If you just want to sanity-check one chart before committing to a full dashboard, ask Claude to generate a single Explorer chart first. Once you like how a metric looks, fold it into the dashboard tile list in Step 1. > [accordion] Using the link in other workflows > > Drop the dashboard link into a QBR deck appendix, a stakeholder email, or a Slack pin — it's a live view, so anyone with the link always sees current data without needing you to re-run anything. *** > [card] [Auto-Build a QBR Deck](/mcp/workflows/qbr-deck-builder) > > Use this dashboard link as a live companion to a static QBR deck. > [card] [Monthly Client Report, Built Automatically](/mcp/workflows/monthly-client-report) > > For a written narrative report instead of a live clickable dashboard. # Find Visibility Gaps Worth Fixing Source: https://developers.scrunch.com/mcp/workflows/find-visibility-gaps MCP workflow to surface your weakest AI visibility topics, identify the specific prompts you're losing, and ship a prioritized content action plan to Notion. This workflow identifies your weakest topic areas, surfaces the specific queries you're losing, checks what competitors and third-party sources are filling the gap, and builds a Notion tracker with content recommendations — all in one go. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Pulling tag-level presence, gap prompts, and citation data | > | Notion MCP | Optional | Creating a prioritized gap tracker database | > | Google Workspace MCP | Optional | Saving the gap analysis as a Google Doc | > > Use the **Scrunch only** tab if you don't have Notion or Google Workspace connected. *** > [tab] Notion > > Replace the bracketed values, then paste. > > ```text theme={null} > For [brand name] in Scrunch, run a visibility gap analysis and build a prioritized action plan. > > Step 1 — Find the weakest topic areas: > Get all tags configured for [brand name]. For each tag, pull presence metrics for the last 30 days. Rank tags by presence rate from lowest to highest. Identify the 3 tags with the lowest presence — these are the priority investment areas. > > Step 2 — Surface the specific missing prompts: > For each of the 3 lowest-performing tags: > - List the prompt variants where [brand name] is not present in the last 30 days > - Show: prompt text, platform, observation count > - Sort by observation count — the most-observed missing prompts are the most urgent > - Get citation metrics for that tag: what share of citations are brand-owned vs. competitor vs. third-party? > > Step 3 — Check the competitive situation: > For the lowest-performing tag, check: are any tracked competitors showing up in these prompts where [brand name] isn't? Which competitor appears most in this gap area? > > Step 4 — Build the Notion tracker: > Create a Notion database titled "[brand name] Visibility Gap Tracker — [month year]" with these columns: Topic Area, Presence Rate, Gap Count, Competitor Winning, Citation Type, Priority, Status. > > Create one row per gap tag. Set Priority based on: lowest presence rate combined with highest total observation count = most urgent. > > Inside each row's page, write: > - The 5 highest-priority missing prompts for that topic area (with prompt text and observation count) > - What competitor or third-party content is filling the gap > - 3 specific content recommendations to close it — whether this is existing content to optimize or something net-new > ``` > > **What you get:** A Notion database you can share with content and SEO teams, with each gap area documented, ranked by urgency, and loaded with specific recommendations. No need to interpret the numbers — Claude does that for you. > [tab] Google Docs > > Replace the bracketed values, then paste. > > ```text theme={null} > For [brand name] in Scrunch, run a visibility gap analysis and save the results as a Google Doc. > > Step 1 — Find the weakest topic areas: > Get all tags configured for [brand name]. For each tag, pull presence metrics for the last 30 days. Rank tags by presence rate from lowest to highest. Identify the 3 tags with the lowest presence — these are the priority investment areas. > > Step 2 — Surface the specific missing prompts: > For each of the 3 lowest-performing tags: > - List the prompt variants where [brand name] is not present in the last 30 days > - Show: prompt text, platform, observation count > - Sort by observation count — the most-observed missing prompts are the most urgent > - Get citation metrics for that tag: what share of citations are brand-owned vs. competitor vs. third-party? > > Step 3 — Check the competitive situation: > For the lowest-performing tag, check: are any tracked competitors showing up in these prompts where [brand name] isn't? Which competitor appears most in this gap area? > > Step 4 — Save to Google Docs: > Create a new Google Doc titled "[brand name] Visibility Gap Analysis — [month year]" in [folder name or Drive location] with this structure: > > ## Summary > The 3 highest-priority gap areas, ranked by urgency, with a one-sentence description of each. > > ## Gap Area 1: [Tag Name] > - Presence rate: [X]% > - Top missing prompts (with observation counts) > - Competitor winning this space: [name] > - Citation breakdown: [brand / competitor / third-party split] > - 3 content recommendations to close the gap > > ## Gap Area 2: [Tag Name] > [same structure] > > ## Gap Area 3: [Tag Name] > [same structure] > > ## Recommended Next Steps > Prioritized action list — what to create or optimize first, and why. > ``` > > **What you get:** A Google Doc you can share with content or SEO teams directly from Drive. Works well when the person acting on the gaps lives in Google Docs, not Notion. > [tab] Scrunch only > > ```text theme={null} > For [brand name] in Scrunch, run a visibility gap analysis. > > 1. Get all tags. For each tag, pull presence metrics for the last 30 days and calculate the presence rate. > 2. Rank tags by presence rate from lowest to highest. Show me the bottom 5. > 3. For the lowest-performing tag, list the specific prompts where [brand name] is not present. Sort by observation count. > 4. Get citation metrics for that tag — what share is going to competitors vs. third parties vs. brand-owned? > 5. Check: which tracked competitor appears most in that tag's gap prompts? > > Give me a prioritized summary: the top 3 topic areas to focus on, the highest-urgency prompt in each, and one specific content recommendation per area. > ``` *** ## Tips > [accordion] What 'observation count' means > > Observation count is how many times Scrunch has run that prompt across AI platforms. Higher observation count = more data points. A prompt with a high observation count where you're absent is a reliable gap, not just a one-off miss. Prioritize those. > [accordion] Refreshing the tracker monthly > > Once the Notion database is created, run the Scrunch-only version monthly and paste the results into the existing database. Ask Claude to "update the existing \[brand name] Visibility Gap Tracker in Notion with this month's data, keeping the same structure." > [accordion] Narrowing by funnel stage > > If you want to focus on one part of the funnel, add a filter: "Do this analysis for consideration-stage prompts only" or "Filter to tags that include 'awareness'". You can run this workflow once per funnel stage if needed. *** > [card] [Competitor Share of Voice, Ranked](/mcp/workflows/competitor-share-of-voice) > > See who's winning in the gaps you just found — and build a displacement map. > [card] [Prompt Library](/mcp/prompts/visibility-overview) > > Deeper gap analysis prompts including citation-level and platform-specific breakdowns. # GSC Query-Gap Prompt Expansion Source: https://developers.scrunch.com/mcp/workflows/gsc-query-gap-expansion Find Google Search Console queries you already rank for that aren't tracked as Scrunch prompts yet, and bulk-create prompts for the top gaps. If a query already sends you organic traffic, you have a reason to know whether AI assistants answer it the same way search does — but you can't know that if Scrunch isn't tracking it. This workflow finds that blind spot and closes it, expanding prompt coverage based on queries you've already proven matter. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Checking existing prompt coverage and creating new prompts | > | Google Search Console MCP | Required | Sourcing real search queries you already rank for | > > Looking for content gaps instead of monitoring gaps? Use [Where Search Rankings and AI Presence Diverge](/mcp/workflows/search-vs-ai-gaps) — that workflow finds pages that need new or improved content. This one just makes sure you're watching the right queries in the first place. *** ```text theme={null} For [brand name] / [domain], find search queries we rank for that aren't tracked as Scrunch prompts yet, and create prompts for the highest-value gaps. Step 1 — Pull our real search queries: From Google Search Console, get the top [50] queries by impressions for [domain] over the last 90 days, where we rank in the top 10. Include impressions, clicks, and average position for each. Step 2 — Check existing coverage: List all prompt variants currently tracked for [brand name] in Scrunch. Compare against the Step 1 query list — which of our top-ranking search queries have no closely-matching Scrunch prompt at all? Step 3 — Prioritize the gaps: Of the uncovered queries, rank by impressions — these are the ones worth monitoring first since they represent proven search demand. Step 4 — Create prompts for the top gaps: For the top [10] uncovered queries, create a Scrunch prompt for each, phrased as a natural question rather than the raw keyword string. Tag each one "gsc-expansion" so we can track this batch separately, and assign the appropriate funnel stage based on query intent (informational = awareness, comparison/branded = consideration or decision). Step 5 — Confirm: List everything created, with the original search query, impressions, and the prompt text Claude generated for it. ``` **What you get:** A batch of new Scrunch prompts sourced directly from queries you already know drive real search traffic — so your AI monitoring coverage starts where your proven search demand already is, instead of guessing. *** ## Tips > [accordion] Rewriting keywords as natural questions > > Search queries are often keyword fragments ("best crm small business"), but AI assistants get asked full questions ("what's the best CRM for a small business"). Step 4 asks Claude to rephrase — check a few of the generated prompts to make sure the intent held up in translation. > [accordion] Re-running this quarterly > > Search rankings and query volume shift over time — re-run this every quarter to catch new queries you've started ranking for since the last pass, rather than treating prompt coverage as a one-time setup task. > [accordion] Filtering by page or section first > > If \[domain] is large, scope Step 1 to a specific subdirectory or page group (e.g. "queries where the ranking page is under /pricing/") to keep this workflow focused on one part of the business at a time. > [accordion] What to do once these prompts have data > > Give new prompts 30 days to accumulate observations, then run the Rankings & Priority Lists prompts from the Prompt Library — the "gsc-expansion" tag makes it easy to filter to just this batch and see how AI presence compares to the search rank you started from. *** > [card] [Where Search Rankings and AI Presence Diverge](/mcp/workflows/search-vs-ai-gaps) > > For finding content fixes rather than monitoring gaps. > [card] [Build Your Prompt Library from SEO Keywords](/mcp/workflows/prompts-from-keywords) > > A broader keyword-list version of this same idea, sourced from Semrush/Ahrefs instead of GSC. # Build an AI Content Brief from Keyword Rankings Source: https://developers.scrunch.com/mcp/workflows/keyword-rankings-to-ai-brief Combine Semrush or Ahrefs keyword rankings with Scrunch citation gaps to prioritize which content to create or fix and what it must say to get cited. Keyword tools tell you what people search for. Scrunch tells you what AI engines answer without citing you. Together, they give you the clearest possible picture of where to invest in content: topics with high search volume, proven buyer intent, and a citation gap you can close. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Citation gaps and AI presence data by topic | > | Semrush MCP | Required for Semrush tab | Keyword rankings, volume, and difficulty | > | Ahrefs export | Required for Ahrefs tab | Keyword rankings — paste a CSV export | > > Choose your keyword tool in the tabs below. Don't have either? Use the [SEO Keywords to Prompts](/mcp/workflows/prompts-from-keywords) workflow instead, which works with any pasted keyword list. *** > [tab] Semrush > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name], use Semrush keyword data and Scrunch citation data together to build a prioritized AI content brief. > > Step 1 — Pull top-ranking keywords from Semrush: > Get the top [50] organic keywords for [domain] ranked in positions 1–20. Show me: keyword, position, monthly search volume, keyword difficulty, and the URL that's ranking. > > Step 2 — Pull Scrunch citation gaps: > In Scrunch for [brand name], get all tags and calculate the citation rate from [brand domain] for each — variants with brand_present = true and citation pointing to [brand domain] divided by total variants. Rank by citation rate from lowest to highest. Also pull presence metrics for the last 30 days. > > Step 3 — Find where SEO authority and AI presence diverge: > Semantically match each Semrush keyword to the closest Scrunch tag. Identify: > - Keywords in positions 1–10 with high search volume but AI citation rate under [30]% > - Keywords where Semrush shows a strong ranking URL but Scrunch shows competitors winning the AI citations for that topic > - Keywords with high volume but no corresponding Scrunch tag (a tracking gap worth fixing) > > Rank these by opportunity: (monthly search volume × keyword difficulty score) ÷ AI citation rate. Higher = more valuable to fix. > > Step 4 — Build the AI content brief: > For the top 3 gap opportunities, write a content brief for each: > - The keyword, search volume, and keyword difficulty > - The Scrunch prompts in this topic where brand is absent (most-observed first) > - What competing content or third-party sources are winning the AI citations > - Recommended content format and angle to win both the search result and the AI citation > - Specific facts, data points, or claim structures that would make this content more citable than what's currently appearing > ``` > > **What you get:** Three ready-to-act content briefs, each grounded in both keyword volume data and AI citation gaps. These are the highest-priority pieces to create or rewrite — backed by two independent data sources pointing at the same opportunity. > [tab] Ahrefs > > Export your keyword rankings from Ahrefs (Site Explorer → Organic Keywords → Export) and paste the data below. > > ```text theme={null} > I'm going to paste Ahrefs keyword ranking data for [domain] below. Use it alongside Scrunch to build a prioritized AI content brief. > > Here's my Ahrefs organic keywords data: > [Paste your keyword, position, volume, and keyword difficulty columns here] > > For [brand name] in Scrunch, get all tags and calculate the citation rate from [brand domain] for each tag. Rank by citation rate from lowest to highest. Also pull presence metrics for the last 30 days. > > Cross-reference the Ahrefs keywords against the Scrunch tags — semantically match each keyword to the closest tag. Find: > - Keywords in positions 1–10 with meaningful search volume but AI citation rate under 30% > - Keywords where the ranking URL has authority but Scrunch shows competitors winning the AI citations for that topic > - High-volume keywords with no corresponding Scrunch tag (worth adding as a tracking prompt) > > Rank by opportunity: highest volume × lowest AI citation rate = most urgent. > > For the top 3 gap opportunities, write a content brief for each: > - Keyword, search volume, and keyword difficulty > - The Scrunch prompts in this topic where brand is absent (most-observed first) > - What's winning the AI citations instead > - Recommended content format and the specific angle that would out-answer what's currently cited > - Facts, data points, or claim structures that would make this content more extractable by AI > ``` > > **What you get:** Three ready-to-act content briefs grounded in both your Ahrefs ranking data and Scrunch citation gaps — the highest-priority pieces to create or rewrite. *** ## Tips > [accordion] Why combine two data sources > > Keyword tools optimize for search engines. Scrunch optimizes for AI engines. A keyword with high volume and a strong ranking page is a proven topic — but if AI isn't citing your page for it, you're getting the search traffic without the AI influence. Combining the two surfaces the topics where a single content improvement wins on both channels simultaneously. > [accordion] When your Semrush keywords don't match any Scrunch tags > > This means your AI tracking coverage has gaps. After running this workflow, add the high-volume keywords as new Scrunch prompts using the SEO Keywords to Prompts workflow — then you'll have data on them for next time. > [accordion] What to do with the content briefs > > Pass them directly into the Create Content for AI Citations workflow — that workflow accepts a brief as input in Step 2 and can publish through your CMS in the same conversation. > [accordion] Running this before a content sprint > > This workflow is most useful at the start of a quarterly content planning cycle. Run it once, get the 3–5 highest-priority briefs, and use those to anchor your sprint. Revisit after the content publishes using the Measure AI Visibility's Impact on Traffic workflow to see what moved. *** > [card] [Create Content That Gets AI Citations](/mcp/workflows/create-content-for-citations) > > Take the content briefs from this workflow and generate the actual content, then publish through your CMS. > [card] [Measure AI Visibility's Impact on Traffic](/mcp/workflows/ai-visibility-traffic-impact) > > After publishing, use this workflow to measure whether improving AI presence drove traffic growth. # Which Cited Pages Actually Convert Source: https://developers.scrunch.com/mcp/workflows/landing-page-citation-impact Cross-reference the specific pages AI engines are citing against Google Analytics conversion data to see which citations are driving more than just traffic. Getting cited is the goal, but not every citation is worth the same. This workflow checks the pages Scrunch shows are being cited against what Google Analytics shows those same pages actually do once someone lands on them — traffic, sure, but also whether they convert. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Identifying which owned pages are being cited by AI, and how often | > | Google Analytics MCP | Required | Traffic and conversion data for those specific pages | > > Looking for the broader before/after presence-vs-traffic story instead of a per-page breakdown? Use [Measure AI Visibility's Impact on Traffic](/mcp/workflows/ai-visibility-traffic-impact) — this workflow is the page-level follow-up once you know visibility is trending up. *** ```text theme={null} For [brand name] in Scrunch, find which of our AI-cited pages are also converting well, and which are getting cited but going nowhere. Step 1 — Find the cited pages: Pull prompt variants filtered to citation_domain = [brand domain]. Sort by observation count. Take the top 15 — these are the specific owned URLs getting cited most, along with which prompts and platforms cite them. Step 2 — Pull the traffic and conversion data: For each of those URLs, get from Google Analytics over the last [30/90] days: - Sessions and users (landing page traffic) - Conversion rate on [your primary conversion event — e.g. form submit, signup, demo request] - Bounce rate Step 3 — Rank the pages into three buckets: - **Working as intended**: high citation count, healthy traffic, and converting at or above site average - **Traffic without conversion**: high citation count and traffic, but converting below average — the page is being found but not closing - **Cited but quiet**: high citation count but low traffic — citations aren't translating into visits yet, worth checking if the cited URL is even the ideal landing experience Step 4 — Recommend action: For "traffic without conversion" pages, what's the likely fix — unclear CTA, mismatched intent, missing trust signals? For "cited but quiet" pages, is this expected (top-of-funnel content) or a sign something's blocking click-through? ``` **What you get:** A page-level view of which citations are actually earning their keep — separating the pages worth protecting and replicating from the ones that need a conversion-focused fix, not more visibility. *** ## Tips > [accordion] Setting the right conversion event > > Be specific in Step 2 about what "conversion" means for your business — a newsletter signup and a demo request are very different bars. If you track multiple conversion events, run this once per event to see if a page performs differently depending on the goal. > [accordion] Why 'cited but quiet' isn't always a problem > > Citations for awareness-stage, educational content are often "cited but quiet" by design — a comparison page or a glossary entry gets referenced by AI far more than clicked directly. Check the prompt's funnel stage from Step 1 before treating this as a fix-it item. > [accordion] Feeding this into content prioritization > > "Traffic without conversion" pages are strong candidates for the Create Content That Gets AI Citations workflow's optimization path — the citation and traffic are already working, so a conversion-focused rewrite has a clear existing audience to improve. > [accordion] Doing this at the topic level instead of per-page > > If you have many cited pages, group Step 1's results by tag or topic instead of listing pages individually — you'll get a cleaner signal on which topic areas convert well versus which just generate visibility. *** > [card] [Measure AI Visibility's Impact on Traffic](/mcp/workflows/ai-visibility-traffic-impact) > > Start here for the broader before/after visibility-to-traffic story. > [card] [Create Content That Gets AI Citations](/mcp/workflows/create-content-for-citations) > > Use these findings to prioritize which cited pages need a conversion-focused rewrite. # Monthly Client Report, Built Automatically Source: https://developers.scrunch.com/mcp/workflows/monthly-client-report Pull a month's worth of visibility data and have Claude write, structure, and save a complete report to Notion — ready to share or drop into a deck. One prompt. Full monthly report. Paste it in at the end of each month and get a structured Notion page with all the analysis, competitive data, and recommendations written for you. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | All visibility, competitive, sentiment, and citation data | > | Notion MCP | Optional | Saving the report as a shareable Notion page | > | Google Workspace MCP | Optional | Saving the report as a Google Doc | *** > [tab] Notion > > ```text theme={null} > For [brand name] in Scrunch, build the complete AI visibility report for [month year]. > > Step 1 — Pull all performance data: > 1. Overall presence rate for the last 30 days > 2. Platform breakdown: presence rate per AI platform, ranked best to worst > 3. Sentiment for the last 30 days: breakdown of positive, neutral, and negative > 4. Citation health: split of brand-owned vs. competitor vs. third-party citations > 5. Share of voice: presence rates for [brand name] and all tracked competitors, ranked > 6. Top 5 topic areas by presence rate — where we're strongest > 7. Bottom 5 topic areas by presence rate — where we're weakest > > Step 2 — Write the report in Notion: > Create a Notion page titled "[Month Year] AI Visibility Report — [brand name]" and structure it exactly like this: > > ## Executive Summary > Two to three sentences: overall visibility health, the single biggest win this month, and the top priority for next month. > > ## Visibility Performance > Platform breakdown table. One sentence on the strongest platform and one on the weakest. > > ## Competitive Position > Share of voice ranking table. Note any competitor that moved significantly. One sentence on our overall competitive standing. > > ## Content Health > Top 5 performing topics (these are working — protect them). Bottom 5 underperforming topics (these need attention). One sentence on citation health. > > ## Recommendations for Next Month > Three specific actions. For each: what to do, which data point justifies it, and what success looks like. > > Format everything for direct copy-paste into a slide deck — use tables, headers, and bullet points throughout. No dense paragraphs. > ``` > > **What you get:** A complete Notion report that's immediately shareable with a client or leadership team, and structured cleanly enough to paste into Google Slides or a PowerPoint. The recommendations section is actionable, not generic — Claude ties each one to a specific number from the data. > [tab] Google Docs > > ```text theme={null} > For [brand name] in Scrunch, build the complete AI visibility report for [month year]. > > Step 1 — Pull all performance data: > 1. Overall presence rate for the last 30 days > 2. Platform breakdown: presence rate per AI platform, ranked best to worst > 3. Sentiment for the last 30 days: breakdown of positive, neutral, and negative > 4. Citation health: split of brand-owned vs. competitor vs. third-party citations > 5. Share of voice: presence rates for [brand name] and all tracked competitors, ranked > 6. Top 5 topic areas by presence rate — where we're strongest > 7. Bottom 5 topic areas by presence rate — where we're weakest > > Step 2 — Write the report as a Google Doc: > Create a new Google Doc titled "[Month Year] AI Visibility Report — [brand name]" in [folder name or Drive location] and structure it exactly like this: > > ## Executive Summary > Two to three sentences: overall visibility health, the single biggest win this month, and the top priority for next month. > > ## Visibility Performance > Platform breakdown table. One sentence on the strongest platform and one on the weakest. > > ## Competitive Position > Share of voice ranking table. Note any competitor that moved significantly. One sentence on our overall competitive standing. > > ## Content Health > Top 5 performing topics (these are working — protect them). Bottom 5 underperforming topics (these need attention). One sentence on citation health. > > ## Recommendations for Next Month > Three specific actions. For each: what to do, which data point justifies it, and what success looks like. > > Format everything for direct copy-paste into a slide deck — use tables, headers, and bullet points throughout. No dense paragraphs. > ``` > > **What you get:** A complete Google Doc report ready to share via Drive link or drop into Google Slides. Works well for teams that collaborate in comments and suggestions directly in Docs. > [tab] Scrunch only > > ```text theme={null} > For [brand name] in Scrunch, build the AI visibility report for [month year]. > > Pull: > 1. Overall presence rate for the last 30 days > 2. Platform breakdown: presence rate per platform, ranked > 3. Sentiment: breakdown of positive, neutral, negative > 4. Citation health: brand-owned vs. competitor vs. third-party > 5. Competitive share of voice: all tracked competitors ranked by presence rate > 6. Top 5 tags by presence rate > 7. Bottom 5 tags by presence rate > > Structure the output as a complete report with these sections: Executive Summary, Visibility Performance, Competitive Position, Content Health, Recommendations for Next Month. > > Write recommendations as specific actions tied to specific numbers — not generic advice. > ``` *** ## Tips > [accordion] Running reports for multiple brands in one session > > Run the full prompt for each brand back-to-back in the same Claude conversation. Claude creates a separate Notion page for each brand. At the end, ask it to "create a summary page in Notion that links to all the individual brand reports from this session" for an agency-style index. > [accordion] Adding a prior-month comparison > > Add this line to Step 1: "Also pull presence metrics for the 30 days before that period so we can show month-over-month trend direction." Claude will then include a comparison column in the platform table and flag meaningful changes. > [accordion] Making the report deck-ready > > If you're dropping this into a presentation, add to the Notion step: "Write each section heading as a slide title, keep each bullet to one line maximum, and bold the key number in each bullet." This makes the Notion page paste cleanly into a deck without reformatting. *** > [card] [Weekly AI Brief, Saved to Notion & Slack](/mcp/workflows/weekly-ai-brief) > > Keep stakeholders updated week-to-week between monthly reports. > [card] [Competitor Share of Voice, Ranked](/mcp/workflows/competitor-share-of-voice) > > Run this first to have competitive context ready for the report. # New Brand Live in One Conversation Source: https://developers.scrunch.com/mcp/workflows/new-brand-live MCP workflow that onboards a brand end to end: creates the brand, adds competitors, and seeds a tagged prompt library from one chat with your AI agent. Paste this in when onboarding a new brand or client. Your AI agent creates everything in Scrunch directly — the brand, competitors, and an initial prompt library tagged by funnel stage — then confirms the setup when it's done. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Notes | > | - | - | - | > | Scrunch MCP | Required | Editor or Admin-level permissions on a Scrunch Agency or Enterprise plan required | > > This workflow uses write operations. Your AI agent will confirm before creating anything — you'll see each step as it runs. *** ```text theme={null} I need to configure a new brand in Scrunch. Let's do the full setup in this conversation. Step 1 — Create the brand: Create a new brand with: - Name: [brand name] - Website: [website.com] - Description: [one or two sentences describing what the brand does and who it serves] Confirm it was created and give me the brand ID. Step 2 — Add competitors: Add these competitors to [brand name]: - [Competitor 1], website: [competitor1.com] - [Competitor 2], website: [competitor2.com] - [Competitor 3], website: [competitor3.com] Confirm all competitors were added. Step 3 — Create awareness-stage prompts: Create 5 prompts for [brand name] that a potential customer would type into an AI assistant at the very top of the funnel — when they're looking for a solution in [category] but don't know [brand name] yet. Write them as natural questions, not keyword strings. Tag each prompt as "awareness". Step 4 — Create consideration and decision prompts: Create 3 consideration-stage prompts (someone actively comparing options in [category]) and 2 decision-stage prompts (someone ready to choose, looking for final confirmation). Tag the consideration prompts as "consideration" and the decision prompts as "decision". Step 5 — Confirm the setup: List everything we just created: brand details, full competitor list, and all prompts grouped by tag. I want to confirm it looks right before data starts collecting. ``` **What you get:** A fully configured Scrunch brand ready to start collecting data. Expect first metrics within 24–48 hours as prompts begin running. After 30 days you'll have enough data to run the [visibility gap analysis](/mcp/workflows/find-visibility-gaps) and [competitive SOV report](/mcp/workflows/competitor-share-of-voice). *** ## Tips > [accordion] Getting better prompt suggestions from your AI agent > > The more specific your brand description in Step 1, the better the generated prompts in Steps 3–4. Include: the product category, the primary audience, and the key problem the brand solves. For example: "B2B SaaS for mid-market HR teams to automate onboarding workflows." > [accordion] Adding more prompts after setup > > Once the brand is live, use the Prompt Gap Analysis prompt from the [Prompt Library](/mcp/prompts/visibility-gaps) to expand coverage systematically. It's designed to build on an initial library rather than start from scratch. > [accordion] Setting up multiple brands at once > > Run the full prompt once per brand in the same conversation. Start each with: "Now let's set up \[brand 2 name]. Same process as before." Your AI agent keeps each brand's configuration separate. *** > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Once 30 days of data are in, run this to see where to focus content investment. > [card] [Prompt Library](/mcp/prompts/visibility-overview) > > Configuration and tag management prompts to keep your setup clean over time. # Build Your Prompt Library from SEO Keywords Source: https://developers.scrunch.com/mcp/workflows/prompts-from-keywords Compare your SEO keyword list against existing Scrunch prompts, cluster the gaps, and create new tracking prompts in one conversation. Your SEO keyword research already tells you what buyers search for. This workflow maps those keywords against your current Scrunch prompt coverage, finds the gaps, converts them into natural-language AI queries, and adds them to Scrunch — so your AI visibility tracking matches your SEO strategy. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Listing existing prompts, creating new ones | > | Keyword data | Required | Paste from any source — see input options below | > | Google Search Console MCP | Optional | Pull queries directly without exporting | > | Ahrefs / SEMrush / Keyword tool | Optional | Paste a CSV export into the prompt | *** ## Keyword input options You don't need a specific tool connected. Claude can work with keyword data in any of these forms: > [tab] Paste a keyword list > > Copy your keywords from any tool (Ahrefs, SEMrush, Keyword Planner, Clearscope, etc.) and paste them directly into the prompt in Step 2. > > ```text theme={null} > Here are the keywords to analyze: > best project management software > project management tools for remote teams > asana vs monday.com > how to manage remote team tasks > ... > ``` > [tab] Google Search Console > > If you have Google Search Console connected as an MCP, replace Step 2 with: > > ```text theme={null} > Pull the top 100 queries by impressions from Google Search Console for [domain] over the last 90 days. Filter to queries with more than 50 impressions. Use those as the keyword input for the gap analysis. > ``` > [tab] CSV from an SEO tool > > Export a keyword report from Ahrefs, SEMrush, or Moz as CSV. Paste the contents or upload the file and reference it in Step 2: > > ```text theme={null} > I've attached a keyword export from [tool name]. Use the "Keyword" column as the input for the gap analysis. Ignore any keywords with fewer than [X] monthly searches. > ``` *** ## The workflow **1. Pull existing prompt coverage from Scrunch** ```text theme={null} List all active prompt variants for [brand name] in Scrunch. I want to see the full seed prompt text for each one so I can map it against keyword data. ``` **2. Run the gap analysis** ```text theme={null} Here is a list of SEO keywords and questions we're targeting for [brand name]: [paste your keyword list here] Compare these against the Scrunch prompts you just pulled. Classify each keyword into one of three buckets: 1. Already covered — there's an existing Scrunch prompt that tracks this topic or a close equivalent 2. Partially covered — we're tracking the general topic but missing this specific angle or intent 3. Not covered — no existing prompt comes close to this keyword Show me the "partially covered" and "not covered" keywords — those are the gaps. ``` **3. Cluster the gaps and generate prompts** ```text theme={null} Take the gap keywords from the previous step and: 1. Group them into topic clusters — keywords that are semantically related and could be addressed by similar content 2. For each cluster, write 2–4 natural-language questions that a user would actually type into an AI assistant to get information on this topic. These should sound like real questions, not keyword strings. 3. For each prompt, note whether the intent is awareness (general research), consideration (comparing options), or decision (ready to choose) Show me the clusters and proposed prompts before creating anything — I want to review them first. ``` **4. Create the approved prompts in Scrunch** Once you've reviewed the proposed prompts: ```text theme={null} Create the following new prompts for [brand name] in Scrunch. Tag each with its funnel stage (awareness / consideration / decision) and also add the tag "[seo-import]" so I can track this batch separately. [list the prompts you approved in the previous step] ``` **5. Confirm and check coverage** ```text theme={null} List all prompts for [brand name] tagged "[seo-import]" to confirm they were created correctly. How many prompts did we add? What's the breakdown by funnel stage? ``` *** ## Tips > [accordion] How many keywords to analyze at once > > Claude handles up to a few hundred keywords in a single prompt well. For larger keyword sets (1,000+), run the analysis in batches by topic cluster or funnel stage — it produces cleaner output and avoids truncation. > [accordion] Prioritizing which gaps to fill first > > After the clustering step, ask: "Rank these gap clusters by commercial relevance for \[brand name] — which topics represent the highest-value buyers if we appear in AI responses for them?" This focuses your new prompts on business impact, not just coverage volume. > [accordion] Running this quarterly > > SEO keyword priorities shift. Run this workflow every quarter with a fresh export. Use the `[seo-import-q[quarter]-[year]]` tag convention so you can track each batch's performance separately and see which keyword-sourced prompts improve your visibility over time. > [accordion] What makes a good AI tracking prompt vs. an SEO keyword > > SEO keywords are often short ("project management software") while effective AI prompts are full questions ("What's the best project management software for a team of 20?"). Claude handles this conversion in Step 3, but you can adjust the output by adding: "Make the prompts more specific — include use-case context, team size, or industry where it makes the question more realistic." *** > [card] [Create Content That Gets AI Citations](/mcp/workflows/create-content-for-citations) > > Once you've added the prompts, use this workflow to create the content that fills those gaps. > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Find gaps from the Scrunch data side — which prompt categories already have the lowest visibility. # Auto-Build a QBR Deck Source: https://developers.scrunch.com/mcp/workflows/qbr-deck-builder Turn a brand's presence, position, sentiment, and citation metrics into a formatted quarterly business review deck in Google Slides or PowerPoint. Building a QBR deck usually means pulling numbers into a doc, then rebuilding them as slides by hand. This workflow skips the middle step: Claude pulls the quarter's metrics from Scrunch and writes the deck directly, slide by slide, in the presentation tool you already use. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Quarterly presence, position, sentiment, and citation data | > | Google Slides MCP or PowerPoint MCP | Required (choose one) | Creating the deck | *** > [tab] Google Slides > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, build a QBR deck in Google Slides covering [start date] to [end date]. > > Step 1 — Pull the quarter's data: > - Presence metrics for the period, plus the prior period for comparison > - Position metrics for the period > - Sentiment breakdown for the period > - Citation metrics broken down by owner (brand, competitor, third-party) > - Share of voice vs. all tracked competitors (see the Competitor Share of Voice workflow if you want the full displacement analysis first) > > Step 2 — Build the deck: > Create a new Google Slides presentation named "[brand name] QBR — [quarter/year]" with these slides: > 1. Title slide: brand name, quarter, "AI Visibility Quarterly Review" > 2. Executive summary: 3-4 bullet points on the quarter's biggest movements (up or down) > 3. Presence trend: this quarter's presence rate vs. last quarter, with the percentage change > 4. Position breakdown: how often we appear top/middle/bottom, with a short interpretation > 5. Sentiment: positive/mixed/negative split, and whether it shifted from last quarter > 6. Citation ownership: brand vs. competitor vs. third-party share, as a simple breakdown > 7. Competitive standing: our share-of-voice rank vs. tracked competitors > 8. Recommended focus for next quarter: 2-3 specific, prioritized actions based on the weakest number above > > Use large, readable numbers on each metric slide — this is a review deck, not a written report. One key number and one supporting line per slide where possible. > > Step 3 — Confirm and share: > Once built, give me the link to the deck so I can review it before the meeting. > ``` > > **What you get:** A shareable Google Slides deck with every quarterly number already placed on its own slide, an executive summary up front, and a next-quarter action slide at the end — ready to present with light editing, not built from a blank deck. > [tab] PowerPoint > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, build a QBR deck in PowerPoint covering [start date] to [end date]. > > Step 1 — Pull the quarter's data: > - Presence metrics for the period, plus the prior period for comparison > - Position metrics for the period > - Sentiment breakdown for the period > - Citation metrics broken down by owner (brand, competitor, third-party) > - Share of voice vs. all tracked competitors (see the Competitor Share of Voice workflow if you want the full displacement analysis first) > > Step 2 — Build the deck: > Create a new PowerPoint presentation named "[brand name] QBR — [quarter/year]" with these slides: > 1. Title slide: brand name, quarter, "AI Visibility Quarterly Review" > 2. Executive summary: 3-4 bullet points on the quarter's biggest movements (up or down) > 3. Presence trend: this quarter's presence rate vs. last quarter, with the percentage change > 4. Position breakdown: how often we appear top/middle/bottom, with a short interpretation > 5. Sentiment: positive/mixed/negative split, and whether it shifted from last quarter > 6. Citation ownership: brand vs. competitor vs. third-party share, as a simple breakdown > 7. Competitive standing: our share-of-voice rank vs. tracked competitors > 8. Recommended focus for next quarter: 2-3 specific, prioritized actions based on the weakest number above > > Use large, readable numbers on each metric slide — this is a review deck, not a written report. One key number and one supporting line per slide where possible. > > Step 3 — Confirm and save: > Once built, confirm the file name and location so I can find it before the meeting. > ``` > > **What you get:** A PowerPoint deck with every quarterly number already placed on its own slide, an executive summary up front, and a next-quarter action slide at the end — ready to present with light editing, not built from a blank deck. *** ## Tips > [accordion] Feeding this from the Explorer instead > > If you'd rather present live, interactive charts instead of static slide images, build an Executive Explorer Dashboard first and drop its link into the deck's appendix — stakeholders who want to dig into a specific metric can click through instead of asking follow-up questions mid-meeting. > [accordion] Running this for multiple brands > > If you manage several client brands, run Step 1 once per brand and ask Claude to hold each brand's numbers in memory before moving to Step 2 — then build all the decks in the same conversation rather than starting over each time. > [accordion] What to do when a metric is flat > > Not every quarter has a dramatic story. If presence, position, and sentiment are all roughly flat, say so directly in the executive summary rather than manufacturing urgency — "stable performance, no action needed" is a legitimate and often reassuring slide. > [accordion] Keeping the deck current between quarters > > Duplicate the deck at the start of the next quarter and ask Claude to replace only the metric slides (3-7) with fresh data, keeping the same structure. This keeps the deck format consistent for stakeholders who see it every quarter. *** > [card] [Executive Explorer Dashboard](/mcp/workflows/executive-explorer-dashboard) > > Build a live, clickable companion dashboard to link from the deck's appendix. > [card] [Monthly Client Report, Built Automatically](/mcp/workflows/monthly-client-report) > > For a written report between QBRs, use this instead — same data, different format. # Where Search Rankings and AI Presence Diverge Source: https://developers.scrunch.com/mcp/workflows/search-vs-ai-gaps MCP workflow that joins Google Search Console queries with Scrunch data to find pages ranking in search but missing from AI responses, your top-ROI fixes. Ranking well in Google and being cited by AI are two different things. This workflow finds the gap between them: queries where you're on page one in search but absent from AI responses. Those are your highest-value content fixes — the authority is already there, the AI just isn't picking you up yet. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | AI presence and citation data by topic | > | Google Search Console MCP | Recommended | Pulling your top search queries directly | > | GSC export | Alternative | Paste a CSV from GSC if you don't have the MCP connected | > > Choose your input method in the tabs below. *** > [tab] Google Search Console MCP > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name], find the queries where we rank well in Google Search but AI engines aren't citing our content. > > Step 1 — Pull search queries from Google Search Console: > Get the top 100 queries for [domain] over the last 90 days, filtered to queries with more than [50] impressions. Show me: query text, impressions, clicks, and average position. > > Step 2 — Pull AI visibility data from Scrunch: > In Scrunch for [brand name], get all tags and pull presence metrics for the last 30 days. For each tag, calculate the presence rate and the citation rate to [brand domain]. > > Step 3 — Cross-reference and find the gaps: > Semantically match each GSC query to the most relevant Scrunch tag. Then identify the queries where: > - You have significant search impressions at position 1–10 in Google, but AI presence is under [30]% > - You're receiving search traffic but AI engines are citing competitors or third parties instead > > Rank by opportunity: highest impressions × lowest AI presence rate = most urgent. > > Step 4 — Summarize the priority list: > Give me a ranked list of the top [5–10] opportunities. For each: the query, search impressions, Google position, current AI presence rate, and what source AI is citing instead of us. > ``` > > **What you get:** A ranked list of content gaps where your existing search authority isn't translating into AI citations. These are the highest-ROI fixes — you don't need to build authority from scratch, you need to restructure content so AI can extract and cite it. > [tab] Paste GSC Data > > Export from Google Search Console (Performance → Queries → Export) and paste the data directly. > > ```text theme={null} > I'm going to paste my Google Search Console query data below. Use it alongside Scrunch to find where I rank well in search but AI doesn't cite my content. > > Here's my GSC data for [domain] over the last 90 days: > [Paste your query, impressions, clicks, and position columns here] > > For [brand name] in Scrunch, get all tags and pull presence metrics for the last 30 days. Calculate the citation rate to [brand domain] for each tag. > > Cross-reference the search queries above against the Scrunch tags — semantically match each query to the closest tag. Find the queries where: > - I have meaningful impressions at position 1–10 but AI presence is under 30% > - Competitors or third parties are getting the AI citations instead > > Rank the top [5–10] opportunities by: highest impressions × lowest AI presence rate. For each, show: the query, impressions, Google position, AI presence rate, and who's winning the AI citation. > ``` > > **What you get:** The same ranked gap list, built from data you pasted rather than a live connection. Works with any GSC export — just include the query, impressions, and position columns. > [tab] Scrunch only > > No GSC data? This version identifies the same type of gap using Scrunch's own data — it just can't cross-reference against actual search positions. > > ```text theme={null} > For [brand name] in Scrunch, find the topic areas where there's strong evidence that content exists and ranks but AI isn't citing it. > > 1. Get all tags and pull presence metrics for the last 30 days. Rank by presence rate lowest to highest. > 2. For the 5 lowest-performing tags, get citation metrics: what share of citations are going to competitors vs. third parties vs. brand-owned? > 3. For the same tags, list the specific prompts where brand_present = false with the highest observation counts — these are the most-asked questions where we're absent. > 4. Check: are there tags where we have some AI presence (10–30%) but it's inconsistent? Those are likely pages that exist but aren't structured for AI citation. > > Give me a prioritized list of the biggest content gaps with a one-line recommendation for each: new content needed, or existing content needs restructuring. > ``` *** ## Tips > [accordion] Why search rank and AI presence can diverge > > Google ranks pages on domain authority, backlinks, and keyword optimization. AI engines cite pages based on how directly and clearly they answer a question — factual specificity, structure, and extractability matter more than authority signals. A page can rank #1 in Google and still never be cited by AI if it's written in a promotional rather than informational style. > [accordion] What to do with the gap list > > Don't create new pages for queries where you already rank. Instead, use the Create Content for AI Citations workflow to restructure existing pages: add a direct answer at the top, rewrite factual sections to be more specific, and reframe headings to match how questions are asked in AI prompts. The goal is to make your existing content more extractable, not replace it. > [accordion] How often to run this > > Run it quarterly — GSC impressions shift as search trends change, and your Scrunch presence improves as you fix content. Each run will surface new gaps and let you retire ones you've already closed. > [accordion] Filtering to high-intent queries only > > Add this to Step 3: "Filter to queries that indicate commercial intent — comparisons, 'best X', 'how to choose X', or branded competitor queries. Exclude navigational queries like '\[brand] login' or '\[brand] pricing'." This keeps the gap list focused on queries where AI citations actually influence buying decisions. *** > [card] [Create Content That Gets AI Citations](/mcp/workflows/create-content-for-citations) > > Once you have the gap list, use this workflow to restructure or create the content that fills it. > [card] [Build Your Prompt Library from SEO Keywords](/mcp/workflows/prompts-from-keywords) > > Turn the queries from this analysis into Scrunch tracking prompts so you can monitor improvement over time. # Draft a Stakeholder Email Update Source: https://developers.scrunch.com/mcp/workflows/stakeholder-email-update Pull this period's AI visibility headlines from Scrunch and have Claude draft a stakeholder email update, staged for your review before sending. Not every update needs a full report or a meeting — sometimes a client or exec just needs three sentences and a number. This workflow pulls the headline metrics and drafts the email for you. It always stops at a draft: you read it, edit it, and send it yourself. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Pulling this period's headline metrics | > | Gmail MCP or Outlook MCP | Required (choose one) | Creating the draft in your inbox | > > This workflow only creates a draft — it will not send anything. Review it in your inbox before hitting send. *** > [tab] Gmail > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, draft a short stakeholder update email in Gmail. > > Step 1 — Pull the headlines: > Get presence, position, sentiment, and citation metrics for the last [7/30] days, compared to the prior period. Identify the single biggest positive movement and, if there is one, the single biggest area of concern. > > Step 2 — Draft the email: > Create a Gmail draft: > To: [recipient email] > Subject: [brand name] AI Visibility Update — [date] > > Body (keep it under 150 words, no more than 2 short paragraphs): > - Open with the headline number and its change (e.g. "Our AI visibility rose X points this [week/month], driven by...") > - One sentence on what's driving the change > - One sentence flagging anything that needs attention, if applicable > - Close with one sentence on what happens next (nothing needed / a recommended action / a heads-up about an upcoming report) > > Sign off as [your name]. > > Step 3 — Confirm: > Tell me the draft is ready and summarize what it says so I can review it before sending. > ``` > > **What you get:** A Gmail draft sitting in your drafts folder, written and ready — you review, tweak the tone if needed, and send. > [tab] Outlook > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, draft a short stakeholder update email in Outlook. > > Step 1 — Pull the headlines: > Get presence, position, sentiment, and citation metrics for the last [7/30] days, compared to the prior period. Identify the single biggest positive movement and, if there is one, the single biggest area of concern. > > Step 2 — Draft the email: > Create an Outlook draft: > To: [recipient email] > Subject: [brand name] AI Visibility Update — [date] > > Body (keep it under 150 words, no more than 2 short paragraphs): > - Open with the headline number and its change (e.g. "Our AI visibility rose X points this [week/month], driven by...") > - One sentence on what's driving the change > - One sentence flagging anything that needs attention, if applicable > - Close with one sentence on what happens next (nothing needed / a recommended action / a heads-up about an upcoming report) > > Sign off as [your name]. > > Step 3 — Confirm: > Tell me the draft is ready and summarize what it says so I can review it before sending. > ``` > > **What you get:** An Outlook draft sitting in your drafts folder, written and ready — you review, tweak the tone if needed, and send. *** ## Tips > [accordion] Keeping it short on purpose > > The 150-word limit in Step 2 is deliberate — this workflow is for the update that doesn't warrant a deck or a report, just a quick, confident status check. If you find yourself wanting to add more, that's usually a sign you want the Weekly AI Brief or Monthly Client Report workflow instead. > [accordion] When there's genuinely nothing to report > > If nothing moved meaningfully, say so directly in Step 2 rather than manufacturing a headline: "Visibility held steady this period — no action needed." A short, honest "all clear" email builds more trust than an overstated one. > [accordion] Sending to multiple stakeholders with different context > > Run Step 2 once per recipient if different stakeholders need different framing (e.g. a client needs the polished version, an internal teammate needs the raw numbers). Ask Claude to create a separate draft for each rather than trying to write one email that serves both audiences. > [accordion] Why this always stops at a draft > > Sending email on your behalf is treated as an action that needs your explicit review every time, not a one-time approval — so this workflow is intentionally designed to hand you a draft rather than send automatically, even if you run it the same way every week. *** > [card] [Weekly AI Brief, Saved to Notion or Google Docs](/mcp/workflows/weekly-ai-brief) > > For a fuller weekly update with more context than a short email allows. > [card] [Weekly Visibility Alert to Slack](/mcp/workflows/weekly-visibility-alert-slack) > > For internal team visibility instead of a stakeholder-facing email. # Switch from Another AI Visibility Tool in One Conversation Source: https://developers.scrunch.com/mcp/workflows/switch-from-another-tool MCP workflow to migrate brands, personas, tags, competitors, and your full prompt library from another AI visibility tool into Scrunch in one chat. Switching from another AI visibility tool? You don't have to rebuild your setup by hand. Run one prompt in your current tool to export everything — brands, personas, tags, alternative names, competitors, and your full prompt library — then paste the result into a Scrunch MCP chat and have your AI agent recreate it all directly. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Notes | > | - | - | - | > | Scrunch MCP | Required | Editor or Admin-level permissions on a Scrunch Agency or Enterprise plan required | > | Your current tool's MCP, CSV export, or settings UI | Required | Any source where your existing configuration is visible — MCP-connected chat, downloaded CSVs, or text copied from a settings page | > > Step 2 uses write operations in Scrunch. Your AI agent will confirm before creating anything — you'll see each step as it runs. *** ## Step 1 — Export your setup Pick the path that matches the tool you're moving off of. > [tab] Tool with MCP or API-connected chat > > Open a chat with the AI assistant that's connected to your current tool's MCP server (or its API), and paste this prompt. It returns a structured, copy-paste-ready dump of your entire configuration. > > ```text theme={null} > Export everything you can read about my AI visibility configuration from the tool you're connected to. Preserve my exact wording where possible — especially for prompt text, brand descriptions, alternative names, and persona definitions. > > ## Categories (output in this order): > > 1. **Brands** — One entry per tracked brand. For each, include: name, primary website/domain, one or two sentence description, alternative names / aliases / variants, and any unique identifier the tool stores. > > 2. **Personas** — Audience personas defined for each brand. Verbatim names and descriptions. Note which brand each persona belongs to. > > 3. **Tags / Topics** — Every tag or topic label used to categorize prompts. Include the label and a one-line meaning if available. Note whether tags are global or scoped to a specific brand. > > 4. **Competitors** — One entry per competitor, grouped under the brand it's tracked for. Include competitor name and website/domain. > > 5. **Prompts** — One entry per tracked prompt. For each, include: the brand it belongs to, the prompt text verbatim, any persona it's assigned to, and any tags applied. > > ## Format: > > Use a section header for each category. Within each category, list one entry per line. Format brand and prompt lines so they're machine-readable: > > - Brand: ` | website: | aliases: | description: ` > - Persona: ` | persona: | description: ` > - Tag: ` | meaning: | scope: ` > - Competitor: ` | competitor: | website: ` > - Prompt: ` | persona: | tags: | prompt: ` > > Preserve original wording. Do not paraphrase prompt text, descriptions, or persona definitions. > > ## Output: > > - Wrap the entire export in a single fenced code block for easy copying. > - After the code block, state whether this is the complete set or whether any category was truncated. If truncated, say which category and roughly how many entries remain. > ``` > > Save the resulting code block — you'll paste it into Scrunch in Step 2. > [tab] Tool with CSV export only > > Download every CSV your current tool offers — usually one for brands, one for prompts, one for competitors, and sometimes a tags or personas export. Then open a fresh chat with any capable AI assistant (Claude, ChatGPT, etc.), paste **all** the CSV contents in one after another, and use this prompt to reformat them. > > ```text theme={null} > I've pasted CSV exports from my AI visibility tool below. Reformat them into a single, structured export I can hand to another tool's AI agent. > > Preserve my exact wording where possible — especially for prompt text, brand descriptions, alternative names, and persona definitions. > > ## Categories (output in this order): > > 1. **Brands** — One entry per brand: name, primary website/domain, description, alternative names / aliases, identifier. > 2. **Personas** — Audience personas per brand, verbatim names and descriptions. > 3. **Tags / Topics** — Every tag or topic label, with a one-line meaning if present in the CSVs. > 4. **Competitors** — One entry per competitor, grouped under its brand. > 5. **Prompts** — One entry per prompt, with brand, persona (if any), tags (if any), and the prompt text verbatim. > > ## Format: > > Section header per category, one entry per line. Use these line shapes: > > - Brand: ` | website: | aliases: | description: ` > - Persona: ` | persona: | description: ` > - Tag: ` | meaning: | scope: ` > - Competitor: ` | competitor: | website: ` > - Prompt: ` | persona: | tags: | prompt: ` > > Do not paraphrase prompt text, descriptions, or persona definitions. > > ## Output: > > - Wrap the entire export in a single fenced code block. > - After the code block, note any fields that were missing from the CSVs (e.g., "no personas column was present"). > > --- CSV content begins below --- > > [paste all CSV contents here] > ``` > [tab] Paste raw text from anywhere > > If your current tool has no MCP, no API, and no CSV export, copy whatever text you can pull from the settings or configuration screens — brand names, prompt lists, persona blurbs, competitor lists, tag labels. Paste it all into a fresh chat with any capable AI assistant and use this prompt to normalize it. > > ```text theme={null} > I've pasted raw text copied from the settings of my AI visibility tool below. The structure is inconsistent — some sections are tables, some are lists, some are paragraphs. Normalize it into a single, structured export. > > Preserve my exact wording where possible — especially for prompt text, brand descriptions, alternative names, and persona definitions. > > ## Categories (output in this order): > > 1. **Brands** — name, primary website/domain, description, alternative names / aliases. > 2. **Personas** — per brand, verbatim names and descriptions. > 3. **Tags / Topics** — every tag label, with a one-line meaning if present. > 4. **Competitors** — per brand, name and website. > 5. **Prompts** — per brand, with persona (if any), tags (if any), and verbatim prompt text. > > ## Format: > > Section header per category, one entry per line: > > - Brand: ` | website: | aliases: | description: ` > - Persona: ` | persona: | description: ` > - Tag: ` | meaning: | scope: ` > - Competitor: ` | competitor: | website: ` > - Prompt: ` | persona: | tags: | prompt: ` > > If a field isn't present in the source text, write `unknown` rather than guessing. Do not paraphrase prompt text or descriptions. > > ## Output: > > - Wrap the entire export in a single fenced code block. > - After the code block, list anything you couldn't confidently place into a category. > > --- pasted text begins below --- > > [paste raw text here] > ``` *** ## Step 2 — Import into Scrunch Open a fresh chat with an AI assistant connected to the Scrunch MCP. Paste the export from Step 1, then paste this prompt directly after it. ```text theme={null} The block above is an export of my AI visibility setup from another tool. Recreate it in Scrunch. Confirm with me after each step before moving on. Step 1 — Parse and confirm: Read the export and tell me: - How many brands you found - How many personas, tags, competitors, and prompts you found - Anything that looks ambiguous, duplicated, or incomplete Wait for me to confirm before writing anything. Step 2 — Create the brands: Create each brand in Scrunch with its name, website, description, and alternative names from the export. After all brands are created, list them back with their new Scrunch brand IDs. Step 3 — Configure personas and tags: For each brand, set up the personas listed in the export. Then create the tags from the export — global tags first, then brand-scoped tags. Confirm when done. Step 4 — Add competitors: For each brand, add the competitors listed in the export with their websites. Confirm the full competitor count per brand when done. Step 5 — Create the prompt library: For each brand, create every prompt from the export. Apply the persona and tags exactly as listed. Use the prompt text verbatim — do not rewrite or paraphrase. Confirm the prompt count per brand when done. Step 6 — Final summary: List everything you created: brands (with IDs), personas per brand, tags, competitors per brand, and prompts per brand grouped by tag. Flag anything you skipped or couldn't import and explain why. ``` **What you get:** A Scrunch organization that mirrors your previous setup — same brands, same personas, same tags, same competitors, same prompts. First metrics begin landing within 24–48 hours as the prompt library starts running. After 30 days you'll have enough data to compare against your old tool side by side. *** ## Tips > [accordion] If your export got truncated > > MCP tool results are typically capped, and very large prompt libraries can spill past the limit. Re-run the Step 1 prompt once per category — "export only brands and personas", then "export only prompts for brand X" — and import the chunks in sequence. Scrunch's import prompt is happy to pick up where it left off if you tell it which brands are already created. > [accordion] If your previous tool used different tag names > > Tag conventions differ across tools. Before Step 5, tell the Scrunch agent how to normalize: e.g., "Map any tag that means top-of-funnel to 'awareness', any comparison tag to 'consideration', and any purchase-intent tag to 'decision'." The agent will apply the mapping consistently across every prompt. > [accordion] Migrating multiple workspaces or clients > > Run Step 1 once per workspace in your old tool. Keep each export separate. Then run Step 2 once per export in its own Scrunch chat so the agent doesn't cross-wire competitors or tags between unrelated brands. > [accordion] Verifying nothing got missed > > After Step 6, ask Scrunch: "List every prompt grouped by brand and tag, with persona where assigned." Diff that against your Step 1 export. Anything missing is usually a tag mapping the agent skipped — point it out and ask the agent to backfill. *** > [card] [New Brand Live in One Conversation](/mcp/workflows/new-brand-live) > > Setting up an additional brand from scratch after the migration is done. > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Once 30 days of data are in, find where your migrated setup is winning and where it's not. # Weekly AI Brief, Saved to Notion or Google Docs Source: https://developers.scrunch.com/mcp/workflows/weekly-ai-brief One prompt pulls this week's visibility data, saves a full brief to Notion or Google Docs, and posts the headline numbers to Slack. Paste this into any Claude conversation with Scrunch connected. With Notion and Slack also connected, Claude handles the full workflow — no exports, no copy-pasting between tabs. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Pulling visibility, sentiment, and competitor data | > | Notion MCP | Optional | Saving the full brief as a Notion page | > | Google Workspace MCP | Optional | Saving the full brief as a Google Doc | > | Slack MCP | Optional | Posting the summary to a channel | > > Don't have Notion or Slack connected? Use the **Scrunch only** tab below — you'll get the same analysis presented in the chat. *** > [tab] Notion + Slack > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, run this week's AI visibility brief. > > Step 1 — Pull the data: > Get presence metrics for [brand name] for the last 14 days. Show me: > - Overall presence rate this week vs. last week, with the percentage point change > - Breakdown by AI platform (ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews) — which platforms improved, which dropped > - Sentiment comparison: this week vs. last week — any shift in the positive/negative balance > - Share of voice vs. all tracked competitors — calculate each brand's presence rate and flag any competitor that moved more than 5 percentage points > > Step 2 — Find the week's most notable changes: > Pull the 5 specific prompts with the biggest change in brand presence this week vs. last week — both the biggest gains and biggest drops. Show the prompt text, platform, and direction of change. > > Step 3 — Save to Notion: > Create a new Notion page titled "[Monday's date] Weekly AI Brief — [brand name]" with this structure: > - Headline metrics: overall presence %, week-over-week change, best and worst platform > - Platform breakdown table > - Sentiment snapshot > - Competitive snapshot: share of voice table, any competitor that moved more than 5 points called out > - Top 5 changes: the prompts with the biggest weekly movement, with context > - Recommended action: one specific thing to address this week based on the data > > Step 4 — Post to Slack: > Post this summary to the [#channel-name] Slack channel: > "📊 [brand name] Weekly AI Brief — [date] > Visibility: [X]% ([+/-Y]pp vs last week) > [One sentence on the most notable finding this week] > [One sentence recommended action] > → Full brief: [link to the Notion page]" > ``` > > **What you get:** A Notion page with all the detail and a Slack post with just what the team needs to act on. The Notion link in the Slack post connects the two. Run this every Monday and you have a permanent weekly archive without any manual work. > [tab] Google Docs + Slack > > Replace the bracketed values, then paste the whole thing into Claude. > > ```text theme={null} > For [brand name] in Scrunch, run this week's AI visibility brief. > > Step 1 — Pull the data: > Get presence metrics for [brand name] for the last 14 days. Show me: > - Overall presence rate this week vs. last week, with the percentage point change > - Breakdown by AI platform (ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews) — which platforms improved, which dropped > - Sentiment comparison: this week vs. last week — any shift in the positive/negative balance > - Share of voice vs. all tracked competitors — calculate each brand's presence rate and flag any competitor that moved more than 5 percentage points > > Step 2 — Find the week's most notable changes: > Pull the 5 specific prompts with the biggest change in brand presence this week vs. last week — both the biggest gains and biggest drops. Show the prompt text, platform, and direction of change. > > Step 3 — Save to Google Docs: > Create a new Google Doc titled "[Monday's date] Weekly AI Brief — [brand name]" in [folder name or Drive location] with this structure: > - Headline metrics: overall presence %, week-over-week change, best and worst platform > - Platform breakdown table > - Sentiment snapshot > - Competitive snapshot: share of voice table, any competitor that moved more than 5 points called out > - Top 5 changes: the prompts with the biggest weekly movement, with context > - Recommended action: one specific thing to address this week based on the data > > Step 4 — Post to Slack: > Post this summary to the [#channel-name] Slack channel: > "📊 [brand name] Weekly AI Brief — [date] > Visibility: [X]% ([+/-Y]pp vs last week) > [One sentence on the most notable finding this week] > [One sentence recommended action] > → Full brief: [link to the Google Doc]" > ``` > > **What you get:** A Google Doc with the full brief and a Slack post linking to it. Works well for teams that share everything through Google Drive and review docs in comment threads. > [tab] Scrunch only > > No Notion or Slack? Paste this and get the full brief in the chat. > > ```text theme={null} > For [brand name] in Scrunch, give me this week's AI visibility brief. > > Pull: > 1. Overall presence rate this week vs. last week — the number and the change > 2. Platform breakdown: presence rate per AI platform for both weeks, ranked by this week's performance > 3. Sentiment this week vs. last week — any notable shift > 4. Share of voice: [brand name] and all tracked competitors, this week vs. last week. Flag any brand that moved more than 5 points. > 5. The 5 prompts with the biggest presence change this week — gains or drops, with prompt text and platform > > Present this as a structured brief. End with a single "Recommended action for this week" based on what you found. > ``` *** ## Tips > [accordion] Setting up recurring Notion pages > > If you run this every Monday, name each page with the week date (e.g., "May 12 Weekly AI Brief — Acme Coffee") so they build into a searchable archive. You can ask Claude to link each week's page to a parent "AI Visibility" Notion database to create a timeline view. > [accordion] Customizing the Slack message > > The Slack format above is intentionally minimal — it's built for a team channel where people skim. If you want a richer Slack post (with a table or more bullet points), add "Format the Slack post with a bullet list instead of a paragraph" to Step 4. > [accordion] Running for multiple brands > > Run the prompt once per brand, each in the same conversation. Claude will keep each brand's data separate and create individual Notion pages and Slack posts for each. *** > [card] [Find Visibility Gaps Worth Fixing](/mcp/workflows/find-visibility-gaps) > > Turn gap analysis into a prioritized Notion tracker with specific content recommendations. > [card] [Prompt Library](/mcp/prompts/visibility-overview) > > Explore 35+ ready-to-copy prompts for deeper analysis and reporting. # Weekly Visibility Alert to Slack Source: https://developers.scrunch.com/mcp/workflows/weekly-visibility-alert-slack Compare this week's presence, position, sentiment, and citation metrics to last week, and post a flagged alert to Slack when a threshold is crossed. Nobody wants a Slack message every week saying "nothing changed." This workflow only speaks up when something crosses a threshold you define — a real alert, not a status update disguised as one. > [!NOTE] > > **Tools used in this workflow** > > | Tool | Required? | Used for | > | - | - | - | > | Scrunch MCP | Required | Week-over-week metric comparison | > | Slack MCP | Required | Posting the alert (or the all-clear) to your team channel | > > Paste this in once a week — manually, or on a recurring schedule if your AI assistant supports one. *** ```text theme={null} For [brand name] in Scrunch, compare this week against last week and alert #[channel-name] on Slack only if something moved significantly. Step 1 — Compare the two weeks: Get presence, position, sentiment, and citation metrics for the last 7 days and the 7 days before that. Calculate the percentage-point change for each. Step 2 — Apply the threshold: Flag anything where: - Presence rate moved more than [5] percentage points in either direction - Sentiment (positive share) dropped more than [5] percentage points - A tracked competitor's share of voice increased by more than [10] percentage points - Citation share to [brand domain] dropped more than [5] percentage points Step 3 — Post to Slack: If anything was flagged in Step 2, post to #[channel-name]: "⚠️ [brand name] AI Visibility Alert — [date] [List each flagged metric with old value → new value and the change] Recommended check: [one sentence on what to look into first]" If nothing was flagged, post a short all-clear instead: "✅ [brand name] AI Visibility — [date]: no significant week-over-week movement. Presence [X]%, sentiment [Y]% positive." ``` **What you get:** A weekly Slack post that's either a real, specific alert worth acting on, or a one-line all-clear — never a wall of numbers nobody reads. *** ## Tips > [accordion] Tuning your thresholds > > The percentage-point thresholds in Step 2 are starting points. If your brand's metrics are naturally noisy week to week, raise them to avoid false alarms; if you track a slower-moving, stable brand, tighten them so real movement doesn't get lost in the "no significant change" bucket. > [accordion] Adding agent traffic to the check > > Extend Step 1 to also pull agent traffic totals for the same two weeks and flag a sudden drop in AI bot crawl volume — a crawl drop can be an early warning sign before it shows up in presence metrics. > [accordion] Routing different severities differently > > If you want sentiment drops to go to a different channel than competitive share-of-voice shifts, split Step 3 into per-metric posts with their own channel targets instead of one combined message. > [accordion] Escalating a repeated alert > > If the same metric gets flagged three weeks running, that's no longer a one-off — add a note to Step 3 asking Claude to call this out explicitly ("this is the third consecutive week presence has declined") so a recurring problem doesn't quietly become the new normal. *** > [card] [Competitor Share of Voice, Ranked](/mcp/workflows/competitor-share-of-voice) > > Run the full competitive analysis when a share-of-voice alert fires. > [card] [Draft a Stakeholder Email Update](/mcp/workflows/stakeholder-email-update) > > For a client-facing version of the same headline numbers, aimed outside the team.