Skip to main content

​
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
  • Response counts
These metrics can be grouped by dimensions including:
  • Date (day, week, month, quarter, year)
  • Prompt or prompt metadata
  • Persona
  • Tag
  • Platform
  • Competitor
  • 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"

​
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_type
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 →