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

​
Date filtering and time granularity

The Responses API supports date-based filtering only.
  • start_date and end_date accept YYYY-MM-DD
  • Timestamp-level filtering is not currently supported
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
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.

​
Pagination model

Responses use Scrunch’s standard paginated collection format: 
{
  "total": 5132,
  "offset": 0,
  "limit": 1000,
  "items": [ ... ]
}
To retrieve the next page: 
offset = offset + limit
For stable ETL jobs, ensure offset increments in multiples of limit.
  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 →