---
title: "List Responses"
method: GET
path: "/{brand_id}/responses"
---

# List Responses

`GET /{brand_id}/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

## Path parameters

- `brand_id` integer, required — The unique identifier for the brand

## Query parameters

- `platform` 'chatgpt' | 'claude' | 'google_ai_overviews' | 'perplexity' | 'meta' | 'google_ai_mode' | 'google_gemini' | 'copilot' | 'grok', nullable — 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
- `prompt_id` integer, nullable — Filter responses to a specific prompt by its ID
- `persona_id` integer, nullable — Filter responses to a specific persona by its ID
- `stage` string, nullable — 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.
- `start_date` string, nullable — Only return responses collected on or after this date (inclusive). Format: YYYY-MM-DD
- `end_date` string, nullable — Only return responses collected before this date (exclusive). Format: YYYY-MM-DD
- `has_shopping_data` boolean, nullable — Filter responses by shopping data presence. True returns only responses with shopping results, False returns only responses without.
- `limit` integer — Maximum number of responses to return per page
- `offset` integer — Number of responses to skip for pagination

## Response `200`

Successful Response

- CollectionResponseResponseListing
  - `total` integer, required
  - `offset` integer
  - `limit` integer, nullable
  - `items` ResponseListing[], required
    - `id` integer, required — Unique identifier for this response
    - `created_at` string, date-time, required — Timestamp when the response was collected
    - `prompt_id` integer, required — ID of the prompt that generated this response
    - `prompt` string, required — The prompt text that was sent to the AI platform
    - `persona_id` integer, nullable, required — ID of the persona used for this response, if any
    - `persona_name` string, nullable — Display name of the persona, if any
    - `country` string, nullable — Country code for the geographic context of this response
    - `stage` string, required — 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` boolean, required — Whether the prompt explicitly mentions the brand
    - `tags` string[] — Custom tags associated with the prompt
    - `key_topics` string[] — Topics associated with the prompt
    - `platform` string, required — The AI platform that generated this response (e.g., chatgpt, claude, perplexity)
    - `brand_present` boolean, required — Whether the brand was mentioned in the AI response
    - `brand_sentiment` string, nullable — 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` string, nullable — 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` string[] — List of competitor names mentioned in the response
    - `response_text` string, required — The full text of the AI-generated response
    - `citations` ResponseCitation[] — URLs cited by the AI platform in this response, with source classification
      - `url` string, required — The full URL of the cited source
      - `domain` string, required — The extracted registered domain from the URL
      - `source_type` string, required — 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` string, nullable — The page title from the citation, when available
      - `snippet` string, nullable — A text snippet or description from the citation, when available
    - `competitors` ResponseCompetitorListing[] — Detailed evaluation data for each configured competitor
      - `id` integer, required — Unique identifier for the competitor
      - `name` string, required — Display name of the competitor
      - `present` boolean, required — Whether the competitor was mentioned in this response
      - `position` 'top' | 'middle' | 'bottom', nullable — 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` 'positive' | 'mixed' | 'negative' | 'none', nullable — 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
    - `query_fanout` QueryFanout — Query fan-out data: search queries an AI engine used internally.
      - `queries` string[], required
      - `engine_metadata` object, nullable
    - `shopping_results` ShoppingResult[] — Shopping product listings surfaced by the AI platform in this response, if any
      - `url` string, required — The URL of the shopping result
      - `title` string, required — The title of the shopping result
      - `image` string, nullable
      - `all_images` string[], nullable
      - `description` string, nullable
      - `rating` number, nullable
      - `reviews` integer, nullable
      - `purchasing_options` ShoppingPurchasingOption[], nullable
        - `price` number, nullable
        - `currency` string, nullable
        - `url` string, nullable
  - `metadata` TimeSeriesMetadata
    - `aggregation_granularity` 'daily' | 'weekly' | 'monthly', required
    - `period_count` integer, required — The number of periods in the time series
    - `start_date` string, date-time, required — The start date of the time series
    - `end_date` string, date-time, required — The end date of the time series
    - `top_domains` TopDomainsMetadata — Metadata about top domains, used by sources/domains endpoints.
      - `domains` TopDomainSummary[], required — Top domains by observation count (always domain-level aggregated)
        - `domain` string, required
        - `domain_owner` string, required
        - `observation_count` integer, required
      - `grand_total` integer, required — Total observation count across all domains (for calculating 'Other')
      - `owner_totals` object, required — Observation counts by owner type (brand, competitor, other)
      - `owner_time_series` OwnerTimeSeriesPoint[], nullable — Time series data by owner type for trend visualization
        - `time_bucket` string, required — Date string for the time bucket (YYYY-MM-DD)
        - `brand` integer, required — Observation count for brand-owned domains
        - `competitor` integer, required — Observation count for competitor-owned domains
        - `other` integer, required — Observation count for third-party domains
      - `segment_totals` SegmentTotal[] — Server-side observation counts per citation segment (covers all domains, not just top-N)
        - `name` string, required
        - `observation_count` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/scrunch/apis/scrunch-data-api.md) · [All operations](https://skmtc.net/scrunch/apis/scrunch-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scrunch/scrunch-data-api/versions/3e09c2a06458/schema)