Query API: Aggregated AI Visibility Metrics

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

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):

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:

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:

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 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.	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.	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.

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

# 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"

# 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:

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:

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:

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:<name> — narrows the competitor branch of the brand grain. Your own brand always stays in the pool.
filters=sub_brand_id:<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:!<name>, sub_brand_id:!<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:

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):

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.

# 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"

# 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"

# 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

# 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

curl "https://api.scrunchai.com/v1/$BRAND_ID/query?fields=position_bucket,brand_presence_percentage" \
  -H "Authorization: Bearer $SCRUNCH_API_KEY"

[
  { "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:

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:

# 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

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

curl -X GET \
  "https://api.scrunchai.com/v1/1234/query?start_date=2024-02-30" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

{
  "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.

Run your first query

Go to the Query API Quickstart →

​Overview

​What the Query API includes

​When to use the Query API

​When not to use the Query API

​Example query

​Two ways to query

​Fields reference

​Dimensions

​Metrics

​Example: citation metrics

​Example: Influence Score for outreach prioritization

​Example: citations broken down by domain topic

​Example: sub-brand citation rate by platform

​Cross-grain pooled presence

​Selecting which entities join the pool

​Supported breakdowns

​Example

​Filtering results

​Dimension filters (filters)

​Metric filters (having)

​Breaking mentions down by a conditional dimension

​Position breakdown

​Crossing with non-conditional dimensions

​Filtering on a conditional dimension

​Date range and validation

​Example: valid request

​Example: invalid date returns 400

​Cardinality and result size

​Limits and performance considerations

​Best practices

​Relationship to the Responses API

Run your first query

Overview

What the Query API includes

When to use the Query API

When not to use the Query API

Example query

Two ways to query

Fields reference

Dimensions

Metrics

Example: citation metrics

Example: Influence Score for outreach prioritization

Example: citations broken down by domain topic

Example: sub-brand citation rate by platform

Cross-grain pooled presence

Selecting which entities join the pool

Supported breakdowns

Example

Filtering results

Dimension filters (`filters`)

Metric filters (`having`)

Breaking mentions down by a conditional dimension

Position breakdown

Crossing with non-conditional dimensions

Filtering on a conditional dimension

Date range and validation

Example: valid request

Example: invalid date returns 400

Cardinality and result size

Limits and performance considerations

Best practices

Relationship to the Responses API