Skip to main content

​
Overview

The Responses API provides row-level access to the full AI responses captured by Scrunch. Each record represents a single AI-generated answer observed on a supported platform and includes the complete response text, citation metadata, and brand and competitor evaluations. This API is designed for teams that need maximum fidelity into how AI platforms answer questions about their category, brand, and competitors. Typical use cases include ETL pipelines, research workflows, full-text analysis, citation audits, internal tooling, and advanced modeling.

​
What the Responses API includes

Each response record may include:
  • Full AI response text (markdown)
  • Citations, including URL, domain, snippet, title, and source type
  • Brand presence, sentiment, and position
  • Competitor presence, sentiment, and position
  • Prompt metadata (persona, tags, key topics, stage)
  • Platform, country, and collection timestamp
  • Query fan-out — the searches the platform ran internally, where exposed
  • Shopping results, where the platform surfaced product listings
Each item corresponds to one AI response, not an aggregate or summary.

​
When to use the Responses API

Choose the Responses API if you need:
  • Per-response visibility instead of averages
  • The exact text produced by AI platforms
  • Citation-level analysis and influence modeling
  • Competitor comparisons within individual responses
  • Custom pipelines or internal UIs built on raw AI output
  • Daily or periodic ingestion jobs using high watermarks
This API is intentionally verbose and optimized for depth and accuracy rather than aggregation.

​
When not to use the Responses API

The Responses API is not ideal if you only need:
  • Aggregated metrics (presence percentage, position score, sentiment score)
  • Lightweight dashboards or BI reporting
  • Trend analysis over time without response text
For those use cases, the Query API is more efficient and better suited.

​
Data mutability and re-evaluation

Not all fields behave the same over time. Immutable fields:
  • response_text
  • citations
  • created_at
  • query_fanout, shopping_results
These reflect exactly what was observed at the time the response was captured. Fields that may be re-evaluated:
  • stage, tags, key_topics
  • brand_present, brand_sentiment, brand_position
  • competitors and competitors_present evaluation fields
These may change if prompt metadata is edited in the Scrunch UI or if brand configuration is updated and re-evaluation is requested. For ETL workflows, always deduplicate or upsert using the globally unique id.

​
Which prompts’ responses are returned

The prompt’s own status is the only filter on historical responses:
  • Responses from active and paused prompts are returned.
  • Responses from archived prompts are excluded.
  • Persona state does not affect visibility. Archiving a persona no longer hides responses from its still-active prompts, so response counts match the prompts you see in Prompt Templates.
id, prompt_id, persona_id, and each competitor’s id are 64-bit integers, not strings. Response IDs are already nine digits, so parsers that coerce large integers into a 32-bit int or a JavaScript Number past 2^53 will corrupt them. Type these columns as INT64 / BIGINT downstream.

​
Request parameters

All parameters are optional. For incremental ingestion:
  1. Pull responses using a date window
  2. Store the created_at value from the latest record
  3. Use that internally as a high watermark
  4. Or load the previous UTC day after midnight to ensure completeness

​
Denormalized response model

Each API item represents a single response with related data embedded as arrays.
  • citations
  • tags
  • key_topics
  • competitors
  • shopping_results
The API does not fan out rows for many-to-many relationships. If you are building dimensional tables or star schemas, you will need to normalize these arrays downstream. This differs intentionally from the Query API, which performs aggregation and grouping.

​
Response schema

​
Collection

Responses use Scrunch’s standard paginated collection format. To retrieve the next page:
For stable ETL jobs, ensure offset increments in multiples of limit.

​
Response

Enum values are returned lowercase — positive, top, brand, chatgpt. A CASE expression or mapping written against capitalized values (Positive, Top) will match nothing and silently yield nulls rather than an error. The exceptions are stage and key_topics, which are returned as display-cased names.
brand_sentiment has four values, and none is not the same as null. none means the brand was mentioned but with no discernible sentiment; null means the brand was not mentioned at all. Scrunch’s own sentiment score excludes none from the average rather than scoring it as neutral.

​
Citation

​
CompetitorEvaluation

The competitors array is not a row per configured competitor — it lists only the competitors mentioned in that response, and is empty when none were. It therefore cannot supply a denominator for competitor presence rate: divide by the total response count instead. See Computing metrics in the data mart guide.

​
ShoppingResult

Present only on responses where the platform surfaced product listings.
  1. Start with start_date (UTC)
  2. Pull responses in batches (limit=1000)
  3. Store created_at from the last record
  4. Use that as the new start date for your next batch
  5. Deduplicate using id (globally unique)

​
Typical downstream uses

Customers commonly use the Responses API to:
  • Audit AI hallucinations or brand misrepresentation
  • Analyze which third-party sources influence AI answers
  • Train internal RAG or evaluation systems
  • Perform NLP or sentiment analysis across competitors
  • Build internal review tools for AI output quality
  • Support custom reporting or research workflows

Get started with Responses

Responses API Quickstart →