Skip to main content

Scrunch API FAQs (Query API & Responses API)

Frequently asked questions around the Scrunch API

Updated this week

Last updated: October 2025

Overview

Scrunch offers two main APIs that customers and partners can use to integrate AI search visibility data into their own systems:

  • Query API: Returns aggregated metrics about brand and competitor presence, sentiment, and citations across prompts, personas, and platforms.

  • Responses API: Returns raw AI responses with full text, citations, and presence/sentiment data for each prompt and platform.

Both APIs are authenticated via bearer tokens and scoped by brand or organization.
​

For complete schema and examples, see:

Frequently Asked Questions

1. What’s the difference between the Query API and the Responses API?

Feature

Query API

Responses API

Purpose

Aggregated reporting for BI or dashboards

Access raw AI response data

Scope

Metrics by prompt, tag, topic, persona, or platform

Individual responses with text, citations, competitors

Best for

Looker Studio or internal analytics

ETL, advanced NLP, or custom UIs

Data volume

Aggregated (e.g. brand_presence_percentage)

High-volume text + JSON payloads

Endpoint

/v1/{brand_id}/query

/v1/{brand_id}/responses

2. How is API authentication handled?

Scrunch uses bearer token authentication:

curl -H "Authorization: Bearer ${SCRUNCH_API_TOKEN}" \ https://api.scrunchai.com/v1/${BRAND_ID}/query?fields=brand_presence_percentage

API tokens can be:

  • Brand-scoped – limited to a single client brand

  • Organization-scoped – covers all brands in your org

To create or manage API keys, go to Organization → Settings → API Keys in your Scrunch dashboard.

Note: To ensure data accuracy and prevent metric overlap, each API call is limited to one brand at a time.

3. How can I use the Responses API?

The Responses API allows you to retrieve full-text AI answers captured by Scrunch, along with citations and metadata for further analysis.

Endpoint:

GET https://api.scrunchai.com/v1/{brand_id}/responses

Common parameters:

  • start_date / end_date – date range for responses (YYYY-MM-DD)

  • platform – e.g. chatgpt, perplexity, google_ai_overviews

  • prompt_id – limit to specific prompt(s)

  • limit / offset – pagination controls

Sample response fields:

  • response_text – full text of AI output

  • citations[] – list of cited URLs, domains, and source types

  • brand_sentiment, brand_position, brand_present

  • competitors[] – includes competitor presence, sentiment, and position

💡 Each Response has a unique ID and is immutable. You can safely deduplicate or upsert data based on this ID.

4. What’s new in the Responses API?

Recent updates include:

  • competitors object — adds per-competitor sentiment and position.

  • competitor_sentiment_score and competitor_position_score are now also available in the Query API for aggregate reporting.

  • Improved citation handling for repeated or mapped sources across ChatGPT and Google AI Mode.

5. How long should I wait before retrieving data for a new brand?

After creating a brand and adding prompts, Scrunch begins collecting responses automatically.
Depending on prompt volume and platforms enabled:

  • Small orgs: ~20–60 minutes

  • Large orgs: up to 12 hours

You can safely query periodically and check the "total" field in the API response to monitor data readiness.

6. How are API usage and billing tracked?

Scrunch does not charge per API call.
​

Usage is based on the number of AI responses collected, not on how often you retrieve them.
​

Adding more brands, prompts, or platforms increases usage, but pulling data via API does not.

7. Can I create brands via API?

Yes.
​

The Configuration API supports creating brand context (name, competitors, websites, personas, topics).

Example:

PUT /v1/brands/{brand_id} {   "competitors": [     { "name": "Competitor A", "websites": ["https://www.example.com"] }   ] }

🧩 The competitor object requires a websites field (array of strings).
​Previously, the field was incorrectly documented as website—this has been corrected.
​

An upcoming Brand Update API will add more flexibility to modify brand and competitor lists without resetting historical data.

8. What should I know about rate limits and sandbox environments?

Currently:

  • There are no enforced rate limits or sandbox restrictions.

  • Data retrieval does not count against your prompt quota.

  • A usage API and sandbox environment are under development for 2026 release.

9. How can I monitor competitor sentiment via API?

You can retrieve competitor sentiment through either:

  • The Query API (aggregated as competitor_sentiment_score)

  • The Responses API (competitors.sentiment per response)

These metrics mirror how brand sentiment is measured but apply per competitor and per prompt.

10. Where can I access the official documentation?

11. What’s next for the Scrunch API?

In development:

  • Usage API: For credit monitoring and org-level metrics

  • Provisioning Status API: To check data readiness after brand creation

  • Expanded Brand Update API: To modify context without data resets

Still need help?
Contact support@scrunchai.com or your Customer Success Manager to request API access or report integration issues.

Related Articles
Frequently Asked Questions (FAQs)
Understanding Your Dashboard
Scrunch: AI Early-Access API Documentation
Understanding Sentiment in Scrunch
Scrunch AI: Early Access Responses API Documentation
Did this answer your question?