> ## 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. # List Responses > Returns AI responses (observations) with full evaluation data, citations, and competitor analysis. Each response represents a single AI-generated answer to a tracked prompt. This endpoint provides the raw response data needed for deep analysis, audits, and research. For aggregated metrics, use the Query API instead. **Response data includes:** - Full response text from the AI platform - Brand evaluation (presence, sentiment, position) - Competitor evaluations with individual metrics - Citations with source classification (brand/competitor/other) - Prompt and persona context ## OpenAPI ````yaml /api-reference/openapi.json get /{brand_id}/responses openapi: 3.1.0 info: title: Scrunch Data API version: 0.1.0 servers: - url: https://api.scrunchai.com/v1 security: [] paths: /{brand_id}/responses: get: summary: List Responses description: >- Returns AI responses (observations) with full evaluation data, citations, and competitor analysis. Each response represents a single AI-generated answer to a tracked prompt. This endpoint provides the raw response data needed for deep analysis, audits, and research. For aggregated metrics, use the Query API instead. **Response data includes:** - Full response text from the AI platform - Brand evaluation (presence, sentiment, position) - Competitor evaluations with individual metrics - Citations with source classification (brand/competitor/other) - Prompt and persona context operationId: listResponses parameters: - name: brand_id in: path required: true schema: type: integer description: The unique identifier for the brand title: Brand Id description: The unique identifier for the brand - name: platform in: query required: false schema: anyOf: - type: string enum: - chatgpt - claude - google_ai_overviews - perplexity - meta - google_ai_mode - google_gemini - copilot - grok - type: 'null' description: |- Filter responses by AI platform. **Supported platforms:** - `chatgpt` - OpenAI ChatGPT - `claude` - Anthropic Claude - `google_ai_overviews` - Google AI Overviews (Search) - `perplexity` - Perplexity AI - `meta` - Meta AI - `google_ai_mode` - Google AI Mode - `google_gemini` - Google Gemini - `copilot` - Microsoft Copilot title: Platform description: |- Filter responses by AI platform. **Supported platforms:** - `chatgpt` - OpenAI ChatGPT - `claude` - Anthropic Claude - `google_ai_overviews` - Google AI Overviews (Search) - `perplexity` - Perplexity AI - `meta` - Meta AI - `google_ai_mode` - Google AI Mode - `google_gemini` - Google Gemini - `copilot` - Microsoft Copilot - name: prompt_id in: query required: false schema: anyOf: - type: integer - type: 'null' description: Filter responses to a specific prompt by its ID title: Prompt Id description: Filter responses to a specific prompt by its ID - name: persona_id in: query required: false schema: anyOf: - type: integer - type: 'null' description: Filter responses to a specific persona by its ID title: Persona Id description: Filter responses to a specific persona by its ID - name: stage in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter responses by customer journey stage. Values are resolved from your brand's configured stages, so they vary per brand. **Default stage sets:** - **Intent (v1)** — `Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other` - **Funnel (v2)** — `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other` Brands that rename or add stages accept those custom names too. title: Stage description: >- Filter responses by customer journey stage. Values are resolved from your brand's configured stages, so they vary per brand. **Default stage sets:** - **Intent (v1)** — `Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other` - **Funnel (v2)** — `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other` Brands that rename or add stages accept those custom names too. - name: start_date in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Only return responses collected on or after this date (inclusive). Format: YYYY-MM-DD title: Start Date description: >- Only return responses collected on or after this date (inclusive). Format: YYYY-MM-DD - name: end_date in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Only return responses collected before this date (exclusive). Format: YYYY-MM-DD title: End Date description: >- Only return responses collected before this date (exclusive). Format: YYYY-MM-DD - name: has_shopping_data in: query required: false schema: anyOf: - type: boolean - type: 'null' description: >- Filter responses by shopping data presence. True returns only responses with shopping results, False returns only responses without. title: Has Shopping Data description: >- Filter responses by shopping data presence. True returns only responses with shopping results, False returns only responses without. - name: limit in: query required: false schema: type: integer minimum: 1 description: Maximum number of responses to return per page default: 100 title: Limit description: Maximum number of responses to return per page - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of responses to skip for pagination default: 0 title: Offset description: Number of responses to skip for pagination responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CollectionResponse_ResponseListing_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: - query components: schemas: CollectionResponse_ResponseListing_: properties: total: type: integer title: Total offset: type: integer title: Offset default: 0 limit: anyOf: - type: integer - type: 'null' title: Limit items: items: $ref: '#/components/schemas/ResponseListing' type: array title: Items metadata: anyOf: - $ref: '#/components/schemas/TimeSeriesMetadata' - type: 'null' type: object required: - total - items title: CollectionResponse[ResponseListing] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ResponseListing: properties: id: type: integer title: Id description: Unique identifier for this response created_at: type: string format: date-time title: Created At description: Timestamp when the response was collected prompt_id: type: integer title: Prompt Id description: ID of the prompt that generated this response prompt: type: string title: Prompt description: The prompt text that was sent to the AI platform persona_id: anyOf: - type: integer - type: 'null' title: Persona Id description: ID of the persona used for this response, if any persona_name: anyOf: - type: string - type: 'null' title: Persona Name description: Display name of the persona, if any country: anyOf: - type: string - type: 'null' title: Country description: Country code for the geographic context of this response stage: type: string title: Stage description: >- Customer journey stage of the prompt. Returned as the display name of the brand's active stage (default sets: intent — `Advice`, `Awareness`, `Evaluation`, `Comparison`, `Other`; funnel — `Awareness`, `Consideration`, `Conversion`, `Loyalty`, `Other`) or a custom stage name. branded: type: boolean title: Branded description: Whether the prompt explicitly mentions the brand tags: items: type: string type: array title: Tags description: Custom tags associated with the prompt default: [] key_topics: items: type: string type: array title: Key Topics description: Topics associated with the prompt default: [] platform: type: string title: Platform description: >- The AI platform that generated this response (e.g., chatgpt, claude, perplexity) brand_present: type: boolean title: Brand Present description: Whether the brand was mentioned in the AI response brand_sentiment: anyOf: - type: string - type: 'null' title: Brand Sentiment description: |- Sentiment of the brand mention: - `positive` - Favorable or recommending tone - `mixed` - Neutral or balanced tone - `negative` - Unfavorable or critical tone - `none` - Mentioned without sentiment brand_position: anyOf: - type: string - type: 'null' title: Brand Position description: |- Where the brand appeared in the response: - `top` - Mentioned in the first third - `middle` - Mentioned in the middle third - `bottom` - Mentioned in the last third competitors_present: items: type: string type: array title: Competitors Present description: List of competitor names mentioned in the response default: [] response_text: type: string title: Response Text description: The full text of the AI-generated response citations: items: $ref: '#/components/schemas/ResponseCitation' type: array title: Citations description: >- URLs cited by the AI platform in this response, with source classification default: [] competitors: items: $ref: '#/components/schemas/ResponseCompetitorListing' type: array title: Competitors description: Detailed evaluation data for each configured competitor default: [] query_fanout: anyOf: - $ref: '#/components/schemas/QueryFanout' - type: 'null' description: >- Search queries generated by the AI platform during query fan-out turns shopping_results: items: $ref: '#/components/schemas/ShoppingResult' type: array title: Shopping Results description: >- Shopping product listings surfaced by the AI platform in this response, if any default: [] type: object required: - id - created_at - prompt_id - prompt - persona_id - stage - branded - platform - brand_present - response_text title: ResponseListing description: >- A complete AI response (observation) with evaluation data, citations, and competitor analysis. Represents a single answer from an AI platform to a tracked prompt. TimeSeriesMetadata: properties: aggregation_granularity: $ref: '#/components/schemas/AggregationGranularity' description: 'The aggregation granularity: daily, weekly, or monthly' period_count: type: integer title: Period Count description: The number of periods in the time series start_date: type: string format: date-time title: Start Date description: The start date of the time series end_date: type: string format: date-time title: End Date description: The end date of the time series top_domains: anyOf: - $ref: '#/components/schemas/TopDomainsMetadata' - type: 'null' description: Top domains metadata (only populated by sources/domains endpoints) type: object required: - aggregation_granularity - period_count - start_date - end_date title: TimeSeriesMetadata ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ResponseCitation: properties: url: type: string title: Url description: The full URL of the cited source domain: type: string title: Domain description: The extracted registered domain from the URL source_type: type: string title: Source Type description: |- Classification of the citation source based on domain ownership: - `brand` - URL belongs to the tracked brand - `competitor` - URL belongs to a configured competitor - `other` - URL belongs to neither brand nor competitor title: anyOf: - type: string - type: 'null' title: Title description: The page title from the citation, when available snippet: anyOf: - type: string - type: 'null' title: Snippet description: A text snippet or description from the citation, when available type: object required: - url - domain - source_type title: ResponseCitation description: >- A citation (source URL) referenced in an AI response, with automatic source classification. ResponseCompetitorListing: properties: id: type: integer title: Id description: Unique identifier for the competitor name: type: string title: Name description: Display name of the competitor present: type: boolean title: Present description: Whether the competitor was mentioned in this response position: anyOf: - type: string enum: - top - middle - bottom - type: 'null' title: Position description: |- Where the competitor appeared in the response: - `top` - Mentioned in the first third of the response - `middle` - Mentioned in the middle third - `bottom` - Mentioned in the last third sentiment: anyOf: - type: string enum: - positive - mixed - negative - none - type: 'null' title: Sentiment description: |- The sentiment of how the competitor was described: - `positive` - Favorable or recommending tone - `mixed` - Neutral or balanced tone - `negative` - Unfavorable or critical tone - `none` - Mentioned without sentiment type: object required: - id - name - present title: ResponseCompetitorListing description: Evaluation data for a competitor mentioned in an AI response. QueryFanout: properties: queries: items: type: string type: array title: Queries engine_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Engine Metadata type: object required: - queries title: QueryFanout description: 'Query fan-out data: search queries an AI engine used internally.' ShoppingResult: properties: url: type: string title: URL description: The URL of the shopping result title: type: string title: Title description: The title of the shopping result image: anyOf: - type: string - type: 'null' title: Image all_images: anyOf: - items: type: string type: array - type: 'null' title: All Images description: anyOf: - type: string - type: 'null' title: Description rating: anyOf: - type: number - type: 'null' title: Rating reviews: anyOf: - type: integer - type: 'null' title: Reviews purchasing_options: anyOf: - items: $ref: '#/components/schemas/ShoppingPurchasingOption' type: array - type: 'null' title: Purchasing Options type: object required: - url - title title: ShoppingResult AggregationGranularity: type: string enum: - daily - weekly - monthly TopDomainsMetadata: properties: domains: items: $ref: '#/components/schemas/TopDomainSummary' type: array title: Domains description: Top domains by observation count (always domain-level aggregated) grand_total: type: integer title: Grand Total description: Total observation count across all domains (for calculating 'Other') owner_totals: additionalProperties: type: integer type: object title: Owner Totals description: Observation counts by owner type (brand, competitor, other) owner_time_series: anyOf: - items: $ref: '#/components/schemas/OwnerTimeSeriesPoint' type: array - type: 'null' title: Owner Time Series description: Time series data by owner type for trend visualization segment_totals: items: $ref: '#/components/schemas/SegmentTotal' type: array title: Segment Totals description: >- Server-side observation counts per citation segment (covers all domains, not just top-N) type: object required: - domains - grand_total - owner_totals title: TopDomainsMetadata description: Metadata about top domains, used by sources/domains endpoints. ShoppingPurchasingOption: properties: price: anyOf: - type: number - type: 'null' title: Price currency: anyOf: - type: string - type: 'null' title: Currency url: anyOf: - type: string - type: 'null' title: Url merchant: anyOf: - type: string - type: 'null' title: Merchant description: >- The name of the merchant or seller offering this purchasing option, when available. type: object title: ShoppingPurchasingOption TopDomainSummary: properties: domain: type: string title: Domain domain_owner: type: string title: Domain Owner observation_count: type: integer title: Observation Count type: object required: - domain - domain_owner - observation_count title: TopDomainSummary OwnerTimeSeriesPoint: properties: time_bucket: type: string title: Time Bucket description: Date string for the time bucket (YYYY-MM-DD) brand: type: integer title: Brand description: Observation count for brand-owned domains competitor: type: integer title: Competitor description: Observation count for competitor-owned domains other: type: integer title: Other description: Observation count for third-party domains type: object required: - time_bucket - brand - competitor - other title: OwnerTimeSeriesPoint description: A single time bucket with observation counts by owner type. SegmentTotal: properties: name: type: string title: Name observation_count: type: integer title: Observation Count type: object required: - name - observation_count title: SegmentTotal description: Observation count for a citation segment, computed server-side. securitySchemes: HTTPBearer: type: http scheme: bearer ````