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
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
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
Data mutability and re-evaluation
Not all fields behave the same over time. Immutable fields:- response_text
- citations
- created_at
- stage, tags, key_topics
- brand_present, brand_sentiment, brand_position
- competitors evaluation fields
Request parameters
All parameters are optional.| Parameter | Type | Description | Notes |
|---|---|---|---|
platform | String (Enum) | AI platform to retrieve responses for | Valid values: chatgpt, claude, google_ai_overviews, perplexity, meta, google_ai_mode, google_gemini |
prompt_id | Number | Specific prompt ID to retrieve responses for | |
start_date | Date (YYYY-MM-DD) | Start date of responses to retrieve | Inclusive |
end_date | Date (YYYY-MM-DD) | End date of responses to retrieve | Exclusive |
limit | Number | Maximum number of responses to return | Must be greater than 1, max 1000 |
offset | Number | Offset for pagination | Should be a multiple of limit |
- Pull responses using a date window
- Store the
created_atvalue from the latest record - Use that internally as a high watermark
- 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
Response schema
Collection
Responses use Scrunch’s standard paginated collection format.| Field | Type | Description | Notes |
|---|---|---|---|
total | Number | Total number of responses available for the current parameters | |
offset | Number | Current offset retrieved | Add limit to this value to retrieve the next page |
limit | Number | Limit applied to the current request | |
items | Response[] | List of Response objects | See below |
limit.
Response
| Field | Type | Description | Notes |
|---|---|---|---|
id | Number | Unique ID for the response | Responses are immutable in normal operations — safe to deduplicate or upsert on id |
created_at | Timestamp (UTC) | Granular timestamp the response was collected at | |
prompt_id | Number | Unique ID for the prompt | Can be retrieved from the Prompts API |
prompt | String | Prompt text | |
persona_id | Number (Nullable) | Persona ID attached to the prompt | |
persona_name | String (Nullable) | Persona name attached to the prompt | |
country | String (Nullable) | 2-character ISO country code the response was retrieved for | |
stage | String (Enum) | Stage of the customer journey | Advice, Awareness, Comparison, Evaluation, Other |
tags | String[] | Tags attached to the prompt | |
key_topics | String[] | Key topics attached to the prompt | |
platform | String (Enum) | AI platform the response was retrieved from | See platform values under Request Parameters |
brand_present | Boolean | Whether the brand is present in the response | |
brand_sentiment | String (Enum) (Nullable) | Sentiment toward the brand | Null when brand not present. Values: Positive, Mixed, Negative, None |
brand_position | String (Enum) (Nullable) | Position of the brand within the response | Null when brand not present. Values: Top, Middle, Bottom |
competitors_present | String[] | List of competitor names found in the response | |
response_text | String | Full AI-generated response text | Markdown format |
citations | Citation[] | Citations included in the response | See Citation below |
competitors | CompetitorEvaluation[] | Per-competitor evaluation data | Superset of the information in competitors_present. See CompetitorEvaluation below |
Citation
| Field | Type | Description | Notes |
|---|---|---|---|
url | String | URL of the citation | |
title | String (Nullable) | Title tag of the citation | Not exposed by all platforms |
snippet | String (Nullable) | Search engine snippet for the citation | Often but not always from the meta description tag. Not exposed by all platforms |
source_type | String (Enum) | Classification of the citation source | Brand, Competitor, Other — “Other” corresponds to third-party in the Scrunch UI |
domain | String | Domain name of the URL | Provided for convenience |
CompetitorEvaluation
| Field | Type | Description | Notes |
|---|---|---|---|
name | String | Name of the competitor | |
id | Number | Unique ID for the competitor | |
present | Boolean | Whether the competitor is present in the response | |
position | String (Enum) (Nullable) | Position of the competitor within the response | Null when present is false. Values: Top, Middle, Bottom |
sentiment | String (Enum) (Nullable) | Sentiment toward the competitor | Null when present is false. Values: Positive, Mixed, Negative, None |
ETL recommended workflow
- Start with
start_date(UTC) - Pull responses in batches (
limit=1000) - Store
created_atfrom the last record - Use that as the new start date for your next batch
- 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 →