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

# Get Collection Analytics Endpoint



## OpenAPI

````yaml /api-reference/openapi/foundation-portal.json get /api/v1/merchants/{merchant_id}/collections/{collection_id}/analytics
openapi: 3.1.0
info:
  title: Depict Foundation Portal API
  version: 1.0.0
  description: >-
    REST API behind the Depict Foundation merchant portal: merchants, products,
    collections, curation, metrics, analytics and search insights. All endpoints
    require an Auth0-issued bearer token.
servers:
  - url: ''
security: []
paths:
  /api/v1/merchants/{merchant_id}/collections/{collection_id}/analytics:
    get:
      tags:
        - Collections
      summary: Get Collection Analytics Endpoint
      operationId: >-
        get_collection_analytics_endpoint_api_v1_merchants__merchant_id__collections__collection_id__analytics_get
      parameters:
        - name: merchant_id
          in: path
          required: true
          schema:
            type: string
            title: Merchant Id
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Collection Id
        - name: market
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Market
        - name: start_timestamp
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            title: Start Timestamp
        - name: end_timestamp
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            title: End Timestamp
        - name: locale
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Locale
        - name: market_group_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Market Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionAnalyticsDetail'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - Auth0: []
components:
  schemas:
    CollectionAnalyticsDetail:
      properties:
        collection_id:
          type: string
          format: uuid
          title: Collection Id
        title:
          type: string
          title: Title
        period:
          $ref: '#/components/schemas/CollectionMetricsPeriod'
        summary:
          $ref: '#/components/schemas/CollectionMetricsSummary'
        scroll_depth:
          anyOf:
            - type: number
            - type: 'null'
          title: Scroll Depth
        inventory:
          $ref: '#/components/schemas/AnalyticsInventoryBreakdown'
        top_products:
          items:
            $ref: '#/components/schemas/AnalyticsProductRef'
          type: array
          title: Top Products
          default: []
        needs_attention:
          items:
            $ref: '#/components/schemas/AnalyticsAttentionProduct'
          type: array
          title: Needs Attention
          default: []
        pinned_vs_auto:
          items:
            $ref: '#/components/schemas/AnalyticsPinnedVsAutoItem'
          type: array
          title: Pinned Vs Auto
          default: []
        sell_through_by_tier:
          items:
            $ref: '#/components/schemas/AnalyticsTierStr'
          type: array
          title: Sell Through By Tier
          default: []
        position_performance:
          items:
            $ref: '#/components/schemas/AnalyticsPositionBand'
          type: array
          title: Position Performance
          default: []
        total_products:
          type: integer
          title: Total Products
          default: 0
      type: object
      required:
        - collection_id
        - title
        - period
        - summary
        - inventory
      title: CollectionAnalyticsDetail
      description: >-
        Rich payload for the Collection Analytics drawer. ``scroll_depth`` is

        always ``None`` for now -- there is no scroll tracking, documented as a
        data

        gap. ``summary`` reuses the same aggregate as the ``/metrics`` endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CollectionMetricsPeriod:
      properties:
        start:
          type: string
          format: date
          title: Start
        end:
          type: string
          format: date
          title: End
      type: object
      required:
        - start
        - end
      title: CollectionMetricsPeriod
    CollectionMetricsSummary:
      properties:
        period:
          $ref: '#/components/schemas/CollectionMetricsPeriod'
        total_revenue:
          $ref: '#/components/schemas/CollectionRevenueMetric'
        total_views:
          $ref: '#/components/schemas/CollectionMetricValue'
        total_clicks:
          $ref: '#/components/schemas/CollectionMetricValue'
        avg_ctr:
          $ref: '#/components/schemas/CollectionRateMetric'
        units_sold:
          $ref: '#/components/schemas/CollectionMetricValue'
        avg_str:
          $ref: '#/components/schemas/CollectionRateMetric'
        add_to_carts:
          allOf:
            - $ref: '#/components/schemas/CollectionMetricValue'
          default:
            value: 0
        dead_stock:
          allOf:
            - $ref: '#/components/schemas/CollectionMetricValue'
          default:
            value: 0
        avg_stock_coverage_days:
          anyOf:
            - type: number
            - type: 'null'
          title: Avg Stock Coverage Days
        rpm:
          allOf:
            - $ref: '#/components/schemas/CollectionRevenueMetric'
          default:
            value: 0
            currency: ''
        velocity:
          allOf:
            - $ref: '#/components/schemas/CollectionMetricValue'
          default:
            value: 0
        auto_lift:
          allOf:
            - $ref: '#/components/schemas/CollectionAutoLift'
          default:
            pinned_ctr: 0
            auto_ctr: 0
        top_product:
          anyOf:
            - $ref: '#/components/schemas/CollectionTopProduct'
            - type: 'null'
      type: object
      required:
        - period
        - total_revenue
        - total_views
        - total_clicks
        - avg_ctr
        - units_sold
        - avg_str
      title: CollectionMetricsSummary
    AnalyticsInventoryBreakdown:
      properties:
        hidden:
          type: integer
          title: Hidden
          default: 0
        low_stock:
          type: integer
          title: Low Stock
          default: 0
        ok:
          type: integer
          title: Ok
          default: 0
        at_risk:
          type: integer
          title: At Risk
          default: 0
        total:
          type: integer
          title: Total
          default: 0
        avg_stock_coverage_days:
          anyOf:
            - type: number
            - type: 'null'
          title: Avg Stock Coverage Days
        variants_in_stock:
          type: integer
          title: Variants In Stock
          default: 0
        variants_total:
          type: integer
          title: Variants Total
          default: 0
        variant_availability_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Variant Availability Pct
      type: object
      title: AnalyticsInventoryBreakdown
      description: >-
        Inventory health for the in-scope products.


        ``hidden`` is the count of manually-hidden products. ``low_stock``
        counts

        visible products with ``0 < inventory <= LOW_STOCK_UNITS``; ``ok``
        counts

        visible products with ``inventory > LOW_STOCK_UNITS``. Fully
        out-of-stock

        visible products (``inventory == 0``) are counted in ``total`` but not
        in

        ``ok``/``low_stock``. ``total`` is the number of in-scope products

        (visible + hidden). ``at_risk`` is ``hidden + low_stock``.

        ``avg_stock_coverage_days`` is ``total_inventory / (units_sold /
        period_days)``

        and ``None`` when nothing sold in the period.


        ``variant_availability_pct`` (0-100) is in-stock variants ÷ total
        variants

        across the in-scope products' size/colour variants
        (``variants_in_stock`` /

        ``variants_total`` are the raw sums). ``None`` when the merchant has no

        variant-level inventory data.
    AnalyticsProductRef:
      properties:
        main_product_id:
          type: string
          title: Main Product Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        sku:
          anyOf:
            - type: string
            - type: 'null'
          title: Sku
        revenue:
          anyOf:
            - type: number
            - type: 'null'
          title: Revenue
        units_sold:
          type: integer
          title: Units Sold
          default: 0
        ctr:
          type: number
          title: Ctr
          default: 0
        rank:
          type: integer
          title: Rank
        position:
          anyOf:
            - type: integer
            - type: 'null'
          title: Position
      type: object
      required:
        - main_product_id
        - rank
      title: AnalyticsProductRef
      description: >-
        A single product row for the analytics drawer's product lists.


        ``ctr`` is a percentage (0-100), computed as ``clicks / views * 100`` to

        match the rest of the collection-metrics module. ``revenue`` is ``None``
        when

        the product's revenue is unknown (multi-currency without FX); ``sku`` is

        always ``None`` for now because a per-main-product SKU is not available
        at

        this aggregation layer (products group multiple variants). ``rank`` is

        1-based within the list it belongs to. ``position`` is the product's
        1-based

        index in the collection's sort order (pinned first, then auto); it is

        ``None`` when the product is not part of that ordered scope.
    AnalyticsAttentionProduct:
      properties:
        main_product_id:
          type: string
          title: Main Product Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        sku:
          anyOf:
            - type: string
            - type: 'null'
          title: Sku
        revenue:
          anyOf:
            - type: number
            - type: 'null'
          title: Revenue
        units_sold:
          type: integer
          title: Units Sold
          default: 0
        ctr:
          type: number
          title: Ctr
          default: 0
        rank:
          type: integer
          title: Rank
        position:
          anyOf:
            - type: integer
            - type: 'null'
          title: Position
        reason:
          type: string
          enum:
            - low_ctr
            - no_sales
            - low_revenue
          title: Reason
      type: object
      required:
        - main_product_id
        - rank
        - reason
      title: AnalyticsAttentionProduct
      description: >-
        A worst-performing product plus why it was flagged. ``no_sales`` means
        it

        had stock but sold nothing; ``low_ctr`` means its CTR is in the bottom

        quartile of the collection; ``low_revenue`` is the fallback for
        otherwise

        weak revenue.
    AnalyticsPinnedVsAutoItem:
      properties:
        main_product_id:
          type: string
          title: Main Product Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        pinned_ctr:
          type: number
          title: Pinned Ctr
          default: 0
        auto_ctr:
          type: number
          title: Auto Ctr
          default: 0
        delta_pts:
          type: number
          title: Delta Pts
          default: 0
        verdict:
          type: string
          enum:
            - better_auto
            - better_pinned
            - no_data
          title: Verdict
      type: object
      required:
        - main_product_id
        - verdict
      title: AnalyticsPinnedVsAutoItem
      description: >-
        Per-pinned-product comparison against the collection's auto-cohort CTR.


        ``pinned_ctr`` is the product's own CTR; ``auto_ctr`` is the aggregate
        CTR of

        all non-pinned products (a documented approximation of the
        counterfactual

        "if this had been auto-sorted"). ``delta_pts`` is ``auto_ctr -
        pinned_ctr``.

        ``verdict`` is ``better_auto`` when auto beats pinned by >0.5pts,

        ``better_pinned`` when pinned beats auto by >0.5pts, else ``no_data``
        (neutral

        band or the product got no views). CTRs are percentages (0-100).
    AnalyticsTierStr:
      properties:
        tier:
          type: integer
          title: Tier
        str_value:
          type: number
          title: Str Value
          default: 0
        product_count:
          type: integer
          title: Product Count
          default: 0
      type: object
      required:
        - tier
      title: AnalyticsTierStr
      description: |-
        Sell-through for one of three contiguous tiers of the sorted collection
        (tier 1 = top of sort). ``str_value`` is a percentage (0-100).
    AnalyticsPositionBand:
      properties:
        band:
          type: string
          enum:
            - hero
            - mid
            - tail
            - bottom
          title: Band
        label:
          type: string
          title: Label
        avg_ctr:
          type: number
          title: Avg Ctr
          default: 0
        clicks:
          type: integer
          title: Clicks
          default: 0
        product_count:
          type: integer
          title: Product Count
          default: 0
      type: object
      required:
        - band
        - label
      title: AnalyticsPositionBand
      description: >-
        Aggregate click-through performance for a contiguous band of positions
        in

        the collection's sort order (pinned first, then auto).


        Bands are fixed by 1-based position: ``hero`` = positions 1-3, ``mid`` =
        4-8,

        ``tail`` = 9-12, ``bottom`` = 13+. ``avg_ctr`` is a percentage (0-100),

        ``clicks / views * 100`` aggregated over the in-band products that have

        metrics. ``clicks`` is the total clicks in the band. ``product_count``
        is the

        number of products present in the ordered scope within the band
        (regardless

        of whether they have metrics). All four bands are always returned, even
        when

        empty.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    CollectionRevenueMetric:
      properties:
        value:
          anyOf:
            - type: number
            - type: 'null'
          title: Value
          default: 0
        currency:
          type: string
          title: Currency
          default: ''
        delta_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta Pct
      type: object
      title: CollectionRevenueMetric
    CollectionMetricValue:
      properties:
        value:
          anyOf:
            - type: number
            - type: 'null'
          title: Value
          default: 0
        delta_pct:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta Pct
      type: object
      title: CollectionMetricValue
    CollectionRateMetric:
      properties:
        value:
          type: number
          title: Value
          default: 0
        delta_pts:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta Pts
      type: object
      title: CollectionRateMetric
    CollectionAutoLift:
      properties:
        score:
          anyOf:
            - type: number
            - type: 'null'
          title: Score
        pinned_ctr:
          type: number
          title: Pinned Ctr
          default: 0
        auto_ctr:
          type: number
          title: Auto Ctr
          default: 0
        delta_pts:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta Pts
      type: object
      title: CollectionAutoLift
      description: >-
        Derived "Auto Lift" score: how the click-through rate of auto-sorted

        (non-pinned) products compares to the merchant's manually pinned
        products.


        ``score`` is normalised to 0-100 where ``50`` means auto and pinned
        perform

        equally, ``100`` means auto CTR is >= 2x pinned CTR, and ``0`` means
        auto

        products get no clicks. Computed as ``clamp(50 * auto_ctr / pinned_ctr,
        0,

        100)``. It is ``None`` when the collection has no pinned products or no

        auto (non-pinned) products, so there is nothing to compare.
        ``pinned_ctr``

        and ``auto_ctr`` are percentages (0-100); ``delta_pts`` is

        ``auto_ctr - pinned_ctr`` in percentage points.
    CollectionTopProduct:
      properties:
        main_product_id:
          type: string
          title: Main Product Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        revenue:
          anyOf:
            - type: number
            - type: 'null'
          title: Revenue
      type: object
      required:
        - main_product_id
      title: CollectionTopProduct
      description: >-
        The highest-revenue product in a collection, for the overview table's

        "Top Product" column. ``image_url`` is the product's first image (or
        None).
  securitySchemes:
    Auth0:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            openid: OpenID Connect
            profile: User profile
            email: User email
          authorizationUrl: https://depict.eu.auth0.com/oauth/authorize
          tokenUrl: https://depict.eu.auth0.com/oauth/token
      x-tokenName: id_token

````