> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Query API: Aggregated AI Visibility Metrics
> 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.
***
## 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 | Full URL of a citation source found in AI responses. Use to analyze which web properties appear most in AI answers. | — | 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. | Not filterable | 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 |
| `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 |
| `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 |
| `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. |
| `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. |
| `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. Not compatible with the `tag` or `prompt_topic` breakdown dimensions (mirrors `brand_share_of_voice` / `competitor_share_of_voice`). |
| `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 | — |
| `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 URL. 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). |
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.
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.
**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.
#### 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: 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`, `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"
```
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`, `position_bucket`, `sentiment_band`, `date`, `date_week`, `date_month`, `date_quarter`, `date_year`.
`source_url`, `domain`, `owner`, `source_domain`, `source_topic`, `prompt`, and `query_fanouts` are not filterable.
### 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` and `sentiment_band` are **conditional dimensions** — they describe how your brand appeared in a response, so they only exist on responses where the brand is actually mentioned:
* `position_bucket`: `top`, `middle`, `bottom`
* `sentiment_band`: `positive`, `mixed`, `negative`, `none`
When you group by either, responses that do not mention the brand are excluded from the breakdown — there is no "not mentioned" row. Alongside `brand_presence_percentage`, 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 `brand_presence_percentage`.
### 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.
### 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"
```
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.
Conditional dimensions describe how the *brand* appears in a response, so they cannot be combined with competitor metrics (`competitor_presence_percentage`, `competitor_position_score`, …) or the `competitor_id` / `competitor_name` dimensions in `fields` — such requests return `HTTP 400`. Competitor *filters* are still allowed. `having` on `brand_presence_percentage` or `competitor_presence_percentage` 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"
}
```
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.
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.
Go to the Query API Quickstart →