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

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	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.	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 — <host>`) 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
`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
`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.	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.
`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.
`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. `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.

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.

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.

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.

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

# 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

# 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: pooled market metrics

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

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

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

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

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.

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.

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

# 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

# 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

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.

Rank distribution

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

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

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.

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

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

​Share of Voice supported breakdowns and filters

​Example: citation metrics

​Example: Influence Score for outreach prioritization

​Example: citations broken down by domain topic

​Example: pooled market metrics

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

​Filter for prompts with no tag or topic

​Filtering by citation source owner

​Metric filters (having)

​Breaking mentions down by a conditional dimension

​Position breakdown

​Rank distribution

​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

Share of Voice supported breakdowns and filters

Example: citation metrics

Example: Influence Score for outreach prioritization

Example: citations broken down by domain topic

Example: pooled market metrics

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

Filter for prompts with no tag or topic

Filtering by citation source owner

Metric filters (`having`)

Breaking mentions down by a conditional dimension

Position breakdown

Rank distribution

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