> ## 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.

# Advertiser Review Aspects Route

> Aspect-sentiment matrix for ONE advertiser — the Brand Details slice.

The service owns platform fallback, the one-member fetch, removal of
self-referential cohort fields, and Brand Library tenancy (operator
ruling 2026-08-17). This route only enforces feature access and
validates the public query value.


## OpenAPI

````yaml /openapi.json get /api/v1/brand-reviews/advertisers/{advertiser_id}/aspects
openapi: 3.1.0
info:
  title: AITasker
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/brand-reviews/advertisers/{advertiser_id}/aspects:
    get:
      tags:
        - Brand Reviews
        - Brand Reviews
      summary: Advertiser Review Aspects Route
      description: |-
        Aspect-sentiment matrix for ONE advertiser — the Brand Details slice.

        The service owns platform fallback, the one-member fetch, removal of
        self-referential cohort fields, and Brand Library tenancy (operator
        ruling 2026-08-17). This route only enforces feature access and
        validates the public query value.
      operationId: >-
        advertiser_review_aspects_route_api_v1_brand_reviews_advertisers__advertiser_id__aspects_get
      parameters:
        - name: advertiser_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Advertiser Id
        - name: platform
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Platform
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewAspectMatrix'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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.
    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
    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

````