> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aitasker.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Review Group Insights Route

> Measured cohort analytics for a tracked Brand Group.

POST rather than GET: the cohort is a client-curated set of advertiser ids
(groups live client-side until the server-groups flag is on), and a set of
up to 60 UUIDs does not belong in a query string. Mirrors the Paid Media
group-insights and board-insights routes.

``brand_id`` scopes the request to a brand the caller owns; the cohort
itself is a set of PUBLIC advertisers, and the owned brand is never
silently added to it — see `reference_advertiser_id`.



## OpenAPI

````yaml /openapi.json post /api/v1/brands/{brand_id}/brand-intelligence/review-group-insights
openapi: 3.1.0
info:
  title: AITasker
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/brands/{brand_id}/brand-intelligence/review-group-insights:
    post:
      tags:
        - Brand Reviews
        - Brand Reviews
      summary: Review Group Insights Route
      description: >-
        Measured cohort analytics for a tracked Brand Group.


        POST rather than GET: the cohort is a client-curated set of advertiser
        ids

        (groups live client-side until the server-groups flag is on), and a set
        of

        up to 60 UUIDs does not belong in a query string. Mirrors the Paid Media

        group-insights and board-insights routes.


        ``brand_id`` scopes the request to a brand the caller owns; the cohort

        itself is a set of PUBLIC advertisers, and the owned brand is never

        silently added to it — see `reference_advertiser_id`.
      operationId: >-
        review_group_insights_route_api_v1_brands__brand_id__brand_intelligence_review_group_insights_post
      parameters:
        - name: brand_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Brand Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandReviewGroupInsightsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandReviewGroupInsightsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    BrandReviewGroupInsightsRequest:
      properties:
        advertiser_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 60
          minItems: 1
          title: Advertiser Ids
        group_label:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
          title: Group Label
        reference_advertiser_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Reference Advertiser Id
        aspect_platform:
          anyOf:
            - type: string
              enum:
                - trustpilot
                - google
            - type: 'null'
          title: Aspect Platform
        all_aspect_platforms:
          type: boolean
          title: All Aspect Platforms
          default: false
      type: object
      required:
        - advertiser_ids
      title: BrandReviewGroupInsightsRequest
      description: The cohort to analyse.
    BrandReviewGroupInsightsResponse:
      properties:
        generated_at:
          type: string
          format: date-time
          title: Generated At
        group_key:
          type: string
          title: Group Key
        group_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Group Label
        reference_advertiser_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Reference Advertiser Id
        sample_is_platform_total:
          type: boolean
          title: Sample Is Platform Total
          default: false
        cohort:
          $ref: '#/components/schemas/ReviewGroupCohort'
        coverage:
          $ref: '#/components/schemas/ReviewGroupCoverage'
        brands:
          items:
            $ref: '#/components/schemas/ReviewGroupBrand'
          type: array
          title: Brands
        reference_brand:
          anyOf:
            - $ref: '#/components/schemas/ReviewGroupBrand'
            - type: 'null'
        available_aspect_platforms:
          items:
            type: string
            enum:
              - trustpilot
              - google
          type: array
          title: Available Aspect Platforms
        aspect_matrix:
          $ref: '#/components/schemas/ReviewAspectMatrix'
        aspect_matrices:
          items:
            $ref: '#/components/schemas/ReviewAspectMatrix'
          type: array
          title: Aspect Matrices
        previous_aspect_matrix:
          anyOf:
            - $ref: '#/components/schemas/ReviewAspectMatrix'
            - type: 'null'
        previous_period:
          anyOf:
            - $ref: '#/components/schemas/ReviewGroupPreviousPeriod'
            - type: 'null'
        findings:
          items:
            $ref: '#/components/schemas/ModuleRuleFinding'
          type: array
          title: Findings
      type: object
      required:
        - generated_at
        - group_key
        - coverage
      title: BrandReviewGroupInsightsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReviewGroupCohort:
      properties:
        brand_count:
          type: integer
          minimum: 0
          title: Brand Count
          default: 0
        measured_brand_count:
          type: integer
          minimum: 0
          title: Measured Brand Count
          default: 0
        total_reviews:
          type: integer
          minimum: 0
          title: Total Reviews
          default: 0
        median_rating:
          anyOf:
            - type: number
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Median Rating
        lowest_rating:
          anyOf:
            - type: number
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Lowest Rating
        highest_rating:
          anyOf:
            - type: number
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Highest Rating
        previous_measured_brand_count:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Measured Brand Count
        previous_total_reviews:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Total Reviews
        previous_median_rating:
          anyOf:
            - type: number
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Previous Median Rating
      type: object
      title: ReviewGroupCohort
      description: |-
        Cohort-level statistics, over GROUP MEMBERS ONLY.

        The user's own brand is never included here even when one is selected —
        see the module docstring.
    ReviewGroupCoverage:
      properties:
        status:
          type: string
          enum:
            - ok
            - single_bucket
            - no_overlap
            - no_data
          title: Status
        reason:
          type: string
          title: Reason
          default: ''
        bucket_size:
          anyOf:
            - type: string
              enum:
                - week
                - month
                - quarter
                - year
            - type: 'null'
          title: Bucket Size
        window_start:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Window Start
        window_end:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Window End
        bucket_count:
          type: integer
          minimum: 0
          title: Bucket Count
          default: 0
        excluded_advertiser_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Excluded Advertiser Ids
        depth_capped_advertiser_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Depth Capped Advertiser Ids
      type: object
      required:
        - status
      title: ReviewGroupCoverage
      description: |-
        What the cohort can honestly be charted over.

        ``status != "ok"`` is a measured outcome with prose, not a failure — the
        caller renders the reason instead of an empty chart.
    ReviewGroupBrand:
      properties:
        advertiser_id:
          type: string
          format: uuid
          title: Advertiser Id
        name:
          type: string
          title: Name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Avatar Url
        industry:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry
        review_count:
          type: integer
          minimum: 0
          title: Review Count
          default: 0
        average_rating:
          anyOf:
            - type: number
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Average Rating
        positive:
          type: integer
          minimum: 0
          title: Positive
          default: 0
        neutral:
          type: integer
          minimum: 0
          title: Neutral
          default: 0
        negative:
          type: integer
          minimum: 0
          title: Negative
          default: 0
        platforms:
          items:
            $ref: '#/components/schemas/ReviewPlatformResponseStats'
          type: array
          title: Platforms
        oldest_review_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Oldest Review At
        newest_review_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Newest Review At
        depth_capped:
          type: boolean
          title: Depth Capped
          default: false
        rating_vs_cohort:
          anyOf:
            - type: number
            - type: 'null'
          title: Rating Vs Cohort
        previous_review_count:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Review Count
        previous_average_rating:
          anyOf:
            - type: number
              maximum: 5
              minimum: 0
            - type: 'null'
          title: Previous Average Rating
        previous_positive:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Positive
        previous_neutral:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Neutral
        previous_negative:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Negative
      type: object
      required:
        - advertiser_id
        - name
      title: ReviewGroupBrand
      description: One brand's measured position in the cohort.
    ReviewAspectMatrix:
      properties:
        platform:
          anyOf:
            - type: string
              enum:
                - trustpilot
                - google
            - type: 'null'
          title: Platform
        aspects:
          items:
            type: string
          type: array
          title: Aspects
        aspect_slugs:
          items:
            type: string
          type: array
          title: Aspect Slugs
        vocabulary_is_core_only:
          type: boolean
          title: Vocabulary Is Core Only
          default: false
        vocabulary_assumed:
          items:
            type: string
          type: array
          title: Vocabulary Assumed
        vocabulary_mixed:
          items:
            type: string
          type: array
          title: Vocabulary Mixed
        min_mentions:
          type: integer
          minimum: 0
          title: Min Mentions
          default: 0
        brands_total:
          type: integer
          minimum: 0
          title: Brands Total
          default: 0
        brands_examined:
          type: integer
          minimum: 0
          title: Brands Examined
          default: 0
        reviews_total:
          type: integer
          minimum: 0
          title: Reviews Total
          default: 0
        reviews_classified_total:
          type: integer
          minimum: 0
          title: Reviews Classified Total
          default: 0
        reviews_examined_total:
          type: integer
          minimum: 0
          title: Reviews Examined Total
          default: 0
        basis_notice:
          type: string
          title: Basis Notice
          default: >-
            Computed over AITasker's depth-capped sample of collected reviews,
            and within that only the reviews we classified — not the platform's
            full review population. Unclassified and uncollected reviews are
            excluded from every figure rather than counted as zero.
        rows:
          items:
            $ref: '#/components/schemas/ReviewAspectRow'
          type: array
          title: Rows
        reference_brand:
          anyOf:
            - $ref: '#/components/schemas/ReviewAspectRow'
            - type: 'null'
      type: object
      title: ReviewAspectMatrix
      description: The comparable grid, plus what stops it being over-read.
    ReviewGroupPreviousPeriod:
      properties:
        bucket_size:
          type: string
          enum:
            - week
            - month
            - quarter
            - year
          title: Bucket Size
        cutoff:
          type: string
          format: date-time
          title: Cutoff
        bucket_count:
          type: integer
          minimum: 2
          title: Bucket Count
      type: object
      required:
        - bucket_size
        - cutoff
        - bucket_count
      title: ReviewGroupPreviousPeriod
      description: >-
        What every ``previous_*`` field on this response was measured over.


        Present ONLY when the cohort's coverage plan holds two or more calendar

        buckets. Its absence is the first-measurement state, and it is the
        single

        switch the client reads: no descriptor, no delta chips anywhere on the

        page — a "First measurement" badge instead. There is no code path that

        emits a ``previous_*`` figure without this block beside it.


        **Definition, and why it is not a new versioning concept.** The bucket

        ladder is the one ``review_coverage.build_coverage_plan`` already chose
        for

        this exact cohort, and ``cutoff`` is the start of its most recent bucket
        —

        the same boundary ``review_trends`` already compares across for the

        rating-movement panel. Extending it to the KPI tiles is plumbing, not a

        second notion of "a period".


        **Basis, stated plainly because it is a floor, not a total.** Current

        figures count the whole collected corpus; previous figures count that

        corpus MINUS the reviews we can prove arrived on or after ``cutoff``. A

        review we hold with no ``reviewed_at`` cannot be proven to have arrived

        this period, so it sits on both sides and contributes nothing to any

        delta. The delta is therefore a floor on real movement — consistent with

        every other count on this surface, which ``REVIEW_SAMPLE_BASIS_NOTICE``

        already discloses as a sample rather than a platform total.
    ModuleRuleFinding:
      properties:
        rule_id:
          type: string
          title: Rule Id
        module:
          type: string
          enum:
            - seo
            - content
            - reviews
            - social
            - google-ads
            - audits
          title: Module
        panel:
          type: string
          title: Panel
        severity:
          type: string
          enum:
            - info
            - opportunity
            - risk
          title: Severity
          default: info
        title:
          type: string
          title: Title
        detail:
          type: string
          title: Detail
        evidence_refs:
          items:
            type: string
          type: array
          title: Evidence Refs
      type: object
      required:
        - rule_id
        - module
        - panel
        - title
        - detail
      title: ModuleRuleFinding
      description: |-
        One deterministic finding emitted by the rule engine.

        Every LLM recommendation must cite one of these ``rule_id``s, so the
        narrative can neither contradict nor exceed the measured layer.
    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
    ReviewPlatformResponseStats:
      properties:
        platform:
          type: string
          title: Platform
        reviews:
          type: integer
          minimum: 0
          title: Reviews
          default: 0
        answered:
          type: integer
          minimum: 0
          title: Answered
          default: 0
        reply_rate:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Reply Rate
        negatives:
          type: integer
          minimum: 0
          title: Negatives
          default: 0
        negatives_answered:
          type: integer
          minimum: 0
          title: Negatives Answered
          default: 0
        median_response_hours:
          anyOf:
            - type: number
            - type: 'null'
          title: Median Response Hours
        latency_measured_over:
          type: integer
          minimum: 0
          title: Latency Measured Over
          default: 0
        previous_reviews:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Reviews
        previous_answered:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Answered
        previous_negatives:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Negatives
        previous_negatives_answered:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Previous Negatives Answered
        previous_reply_rate:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Previous Reply Rate
      type: object
      required:
        - platform
      title: ReviewPlatformResponseStats
      description: Reply behaviour on ONE platform. Never pooled across platforms.
    ReviewAspectRow:
      properties:
        advertiser_id:
          type: string
          format: uuid
          title: Advertiser Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        reviews_total:
          type: integer
          minimum: 0
          title: Reviews Total
          default: 0
        reviews_classified:
          type: integer
          minimum: 0
          title: Reviews Classified
          default: 0
        reviews_examined:
          type: integer
          minimum: 0
          title: Reviews Examined
          default: 0
        reviews_unclassified:
          type: integer
          minimum: 0
          title: Reviews Unclassified
          default: 0
        reviews_not_examined:
          type: integer
          minimum: 0
          title: Reviews Not Examined
          default: 0
        reviews_no_aspect_found:
          type: integer
          minimum: 0
          title: Reviews No Aspect Found
          default: 0
        segment:
          anyOf:
            - type: string
            - type: 'null'
          title: Segment
        segment_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Segment Source
        cells:
          items:
            $ref: '#/components/schemas/ReviewAspectCell'
          type: array
          title: Cells
      type: object
      required:
        - advertiser_id
      title: ReviewAspectRow
      description: One brand's row across the comparable aspects.
    ReviewAspectCell:
      properties:
        aspect:
          type: string
          title: Aspect
        mentions:
          type: integer
          minimum: 0
          title: Mentions
          default: 0
        positive:
          type: integer
          minimum: 0
          title: Positive
          default: 0
        negative:
          type: integer
          minimum: 0
          title: Negative
          default: 0
        mixed:
          type: integer
          minimum: 0
          title: Mixed
          default: 0
        neutral:
          type: integer
          minimum: 0
          title: Neutral
          default: 0
        positive_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Positive Pct
        negative_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Negative Pct
        cohort_median_positive_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Cohort Median Positive Pct
        cohort_median_negative_pct:
          anyOf:
            - type: number
              maximum: 100
              minimum: 0
            - type: 'null'
          title: Cohort Median Negative Pct
        positive_delta_pp:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Positive Delta Pp
        negative_delta_pp:
          anyOf:
            - type: number
              maximum: 100
              minimum: -100
            - type: 'null'
          title: Negative Delta Pp
        benchmark_brand_count:
          type: integer
          minimum: 0
          title: Benchmark Brand Count
          default: 0
        not_measured_reason:
          anyOf:
            - type: string
              enum:
                - brand_not_classified
                - aspect_never_mentioned
                - too_few_mentions
            - type: 'null'
          title: Not Measured Reason
        evidence:
          items:
            $ref: '#/components/schemas/ReviewAspectEvidence'
          type: array
          maxItems: 3
          title: Evidence
      type: object
      required:
        - aspect
      title: ReviewAspectCell
      description: >-
        One (brand, aspect) cell.


        Every share is ``| None`` and every count defaults to 0, which is the
        right

        way round: a count of zero is a real measurement ("nobody said this"),
        while

        a share of zero would be a claim we usually cannot support. When

        ``positive_pct`` is None, ``not_measured_reason`` says which of the
        three

        unmeasured states applies — they are different findings and a heat cell
        that

        renders them identically is lying about two of them.
    ReviewAspectEvidence:
      properties:
        review_id:
          type: string
          format: uuid
          title: Review Id
        sentiment:
          type: string
          enum:
            - positive
            - negative
            - mixed
            - neutral
          title: Sentiment
        evidence:
          type: string
          maxLength: 300
          minLength: 1
          title: Evidence
        evidence_rank:
          type: integer
          maximum: 3
          minimum: 1
          title: Evidence Rank
        platform:
          type: string
          maxLength: 20
          title: Platform
        reviewer_name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Reviewer Name
        reviewed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Reviewed At
        source_url:
          type: string
          maxLength: 2048
          minLength: 1
          title: Source Url
      type: object
      required:
        - review_id
        - sentiment
        - evidence
        - evidence_rank
        - platform
        - source_url
      title: ReviewAspectEvidence
      description: >-
        One bounded, classifier-verified excerpt behind a matrix cell.


        Review text is attacker-controlled. The API returns plain text only;
        clients

        must render ``evidence`` as a text child and never as HTML.
        ``evidence_rank``

        is the deterministic newest-first rank within one (brand, aspect) cell.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````