> ## Documentation Index > Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt > Use this file to discover all available pages before exploring further. # Responses API: Raw AI Answers and Citations > Retrieve every raw AI response Scrunch collects with full text, citations, sentiment, competitor evaluations, persona, and platform metadata. ## 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. *** ## 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` | 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. *** ## 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 | To retrieve the next page: ``` offset = offset + limit ``` For stable ETL jobs, ensure offset increments in multiples of `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 | Stage of the customer journey the prompt is mapped to. Values are resolved from your brand's configured stages, so they vary per brand. Default sets: intent — `Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other`; funnel — `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other`. Brands that rename or add stages return those custom names. | | | `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 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 Responses API Quickstart →