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

# Get cross-version analytics comparison insights

> Computes deterministic red flags / proactive insights across versions (metric degradation, metric improvement, cost outlier, latency outlier), plus a fail-open LLM-generated narrative summary. When versionIds is omitted, all versions present in the analytics data are compared. See [Platform Overview](https://docs.galtea.ai/introduction).



## OpenAPI

````yaml https://api.galtea.ai/openapi.json get /analytics/insights/comparison
openapi: 3.0.0
info:
  version: 1.0.0
  title: Product Management Service API
  description: API documentation for Product Management Service
  contact:
    name: Galtea AI
servers:
  - url: https://api.galtea.ai
security:
  - bearerAuth: []
tags: []
externalDocs:
  description: Galtea Platform Documentation
  url: https://docs.galtea.ai
paths:
  /analytics/insights/comparison:
    get:
      tags:
        - analytics
      summary: Get cross-version analytics comparison insights
      description: >-
        Computes deterministic red flags / proactive insights across versions
        (metric degradation, metric improvement, cost outlier, latency outlier),
        plus a fail-open LLM-generated narrative summary. When versionIds is
        omitted, all versions present in the analytics data are compared. See
        [Platform Overview](https://docs.galtea.ai/introduction).
      operationId: compareAnalyticsInsights
      parameters:
        - name: productId
          in: query
          description: Product ID (required)
          required: true
          schema:
            type: string
        - name: versionIds
          in: query
          style: form
          explode: true
          description: >-
            Version IDs to compare. When omitted, all versions present in the
            analytics data are compared.
          required: false
          schema:
            type: array
            items:
              type: string
        - name: testIds
          in: query
          style: form
          explode: true
          description: Filter by test IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: metricIds
          in: query
          style: form
          explode: true
          description: Filter by metric IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: languages
          in: query
          style: form
          explode: true
          description: Filter by language codes
          required: false
          schema:
            type: array
            items:
              type: string
        - name: from
          in: query
          description: Start date for filtering
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: End date for filtering
          required: false
          schema:
            type: string
            format: date-time
        - name: includeNarrative
          in: query
          description: >-
            When true (default), a fail-open LLM-generated narrative summary is
            computed and returned alongside the deterministic flags. When false,
            the narrative LLM call is skipped entirely and the response carries
            `narrative: null` and `narrativeGeneratedByAi: false`; the
            deterministic flags are unchanged. Machine consumers that produce
            their own prose should pass false to avoid the wasted LLM call.
          required: false
          schema:
            type: boolean
            default: true
        - name: isProduction
          in: query
          description: >-
            When set, returns only production (true) or only development (false)
            data. Omit to include both.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Cross-version analytics comparison insights computed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsInsightsComparison'
        '400':
          description: Missing required productId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    AnalyticsInsightsComparison:
      type: object
      description: >-
        Cross-version analytics comparison insights: deterministic flags plus a
        fail-open LLM-generated narrative summary (the narrative is omitted when
        the request sets `includeNarrative=false`).
      properties:
        productId:
          type: string
          example: prod_123
        versionIds:
          type: array
          items:
            type: string
          example:
            - ver_122
            - ver_123
        status:
          type: string
          enum:
            - all_good
            - flags_present
          example: flags_present
        flags:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsInsightFlag'
        narrative:
          type: string
          nullable: true
          description: >-
            LLM-generated narrative summary, or null when generation was skipped
            (`includeNarrative=false` or no flags) or failed.
          example: >-
            Faithfulness regressed from v2 to v3 while latency on v3 is 1.6× the
            cheapest version.
        narrativeGeneratedByAi:
          type: boolean
          description: >-
            True when the narrative was successfully produced by the LLM; false
            otherwise (including when `includeNarrative=false`).
      required:
        - productId
        - versionIds
        - status
        - flags
        - narrativeGeneratedByAi
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
    AnalyticsInsightFlag:
      type: object
      description: >-
        A single deterministic red flag / proactive insight computed over the
        analytics aggregation. Contextual fields are populated only when they
        apply to the flag type.
      properties:
        type:
          type: string
          enum:
            - low_metric_score
            - low_specification_score
            - coverage_gap
            - metric_degradation
            - metric_improvement
            - cost_outlier
            - latency_outlier
          example: low_metric_score
        severity:
          type: string
          enum:
            - critical
            - warning
            - info
            - positive
          example: critical
        title:
          type: string
          example: 'Low score: Faithfulness'
        description:
          type: string
          example: >-
            Faithfulness scored 42% on v3; 12 of 78 evaluations scored zero
            (15.4%).
        testType:
          type: string
          nullable: true
          example: QUALITY
        versionId:
          type: string
          nullable: true
          example: ver_123
        versionName:
          type: string
          nullable: true
          example: v3
        metricId:
          type: string
          nullable: true
          example: metric_123
        metricName:
          type: string
          nullable: true
          example: Faithfulness
        specificationId:
          type: string
          nullable: true
          example: spec_123
        currentValue:
          type: number
          nullable: true
          example: 42
        comparisonValue:
          type: number
          nullable: true
          example: 71
        unit:
          type: string
          nullable: true
          enum:
            - '%'
            - ms
            - USD
            - tokens
          example: '%'
        failureRate:
          type: number
          nullable: true
          description: >-
            Percentage (0-100) of the metric's scored evaluations that scored
            exactly zero within the request filters; null when the stats were
            unavailable.
          example: 15.4
        evaluationCount:
          type: number
          nullable: true
          description: >-
            Scored evaluations behind failureRate; null when the stats were
            unavailable.
          example: 78
      required:
        - type
        - severity
        - title
        - description
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authorization. Pass your API key in the Authorization header as
        a Bearer token. Both new (`gsk_*`) and legacy (`gsk-`) API keys are
        accepted, e.g. `Authorization: Bearer gsk_...` or `Authorization: Bearer
        gsk-...`.

````