> ## Documentation Index
> Fetch the complete documentation index at: https://juspay-78-sa-banks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Cost Clusters

> Learned per-dimension cost clusters (network/funding/country/currency/IC category) with modelled and effective fees.



## OpenAPI

````yaml decision_engine_openapi-specs.json GET /merchant-account/{merchant_id}/cost-clusters
openapi: 3.1.0
info:
  title: Decision Engine
  description: >-
    Open-source payment gateway routing service by Juspay. Selects the optimal
    payment processor for each transaction in real-time using success-rate
    scoring, rule-based routing, and elimination logic.


    ## Authentication


    This API supports two authentication methods:


    1. **JWT Bearer Token** - For dashboard/user sessions
       - Header: `Authorization: Bearer <jwt_token>`
       - Obtain via `/auth/login` endpoint

    2. **API Key** - For service-to-service/programmatic access
       - Header: `x-api-key: DE_<64_char_hex>`
       - Create via `/api-key/create` endpoint

    Protected endpoints require one of these authentication methods.
  version: 1.4.0
  contact:
    name: Juspay
    url: https://github.com/juspay/decision-engine
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
  - url: http://localhost:8080
    description: Local development
  - url: https://sandbox.hyperswitch.io
    description: 'Hyperswitch sandbox with x-feature: decision-engine'
security: []
tags:
  - name: Health
    description: Service liveness, readiness, and diagnostics
  - name: Auth
    description: Dashboard auth and merchant selection
  - name: API Keys
    description: Service-to-service API key management
  - name: Gateway Decision
    description: Core routing decision APIs
  - name: Score Feedback
    description: Feed transaction outcomes back to improve SR scoring
  - name: Merchant Account
    description: Merchant configuration management
  - name: Routing Rules
    description: Euclid declarative routing rules engine
  - name: Rule Configuration
    description: Service-level SR/elimination config
  - name: Config
    description: Routing key and dimension metadata
  - name: Analytics
    description: ClickHouse-backed analytics and audit reads
  - name: Compatibility
    description: Legacy compatibility routes
  - name: Connector Costs
  - name: Merchant Features
  - name: Autopilot
paths:
  /merchant-account/{merchant_id}/cost-clusters:
    get:
      tags:
        - Connector Costs
      summary: List Cost Clusters
      description: >-
        Learned per-dimension cost clusters (network/funding/country/currency/IC
        category) with modelled and effective fees.
      operationId: listCostClusters
      parameters:
        - name: merchant_id
          in: path
          required: true
          schema:
            type: string
          example: merchant_demo
        - name: limit
          in: query
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int32
        - name: connector
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: account
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: report_date
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ClusterFee'
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
components:
  schemas:
    ClusterFee:
      type: object
      properties:
        key:
          type: string
          description: Opaque cluster key, used in the override PUT/DELETE path.
        connector:
          type: string
        card_network:
          type: string
        variant:
          type: string
        funding:
          type: string
        issuer_country:
          type: string
        currency:
          type: string
        ic_category:
          type: string
        'n':
          type: integer
          format: int64
          description: >-
            Transaction count. 0 for an override-only cluster no longer in the
            top set.
        gross_sum:
          type: number
          format: double
        model_pct_bps:
          type:
            - number
            - 'null'
          format: double
        model_fixed:
          type:
            - number
            - 'null'
          format: double
        override_pct_bps:
          type:
            - number
            - 'null'
          format: double
        override_fixed:
          type:
            - number
            - 'null'
          format: double
        override_updated_at:
          type:
            - string
            - 'null'
        effective_pct_bps:
          type:
            - number
            - 'null'
          format: double
          description: Null when the cluster has no usable rate at all.
        effective_fixed:
          type:
            - number
            - 'null'
          format: double
        source:
          type: string
          enum:
            - override
            - model
            - segmented
        verdict:
          type: string
          description: >-
            `GOOD`, `THIN`, `NON_LINEAR`, or `""` for an override-only cluster.
            A non-GOOD rate is shown so it can be corrected - it is not what the
            router trusts.
        card_product:
          type: string
          description: >-
            Issuer BIN's dominant interchange rate as integer bps (`"115"`), or
            `""` when the report carried no PAN.
        segments:
          type: array
          items:
            $ref: '#/components/schemas/ApiClusterSegment'
          description: >-
            Recovered per-segment rates for a capped/tiered cluster. Empty for
            an ordinary GOOD cluster.
    ApiClusterSegment:
      type: object
      properties:
        seg_idx:
          type: integer
        lo:
          type: number
          format: double
          description: Inclusive lower bound of the amount range this piece prices.
        hi:
          type: number
          format: double
          description: Exclusive upper bound.
        pct_bps:
          type:
            - number
            - 'null'
          format: double
        fixed:
          type:
            - number
            - 'null'
          format: double
        bps_rmse:
          type:
            - number
            - 'null'
          format: double
        'n':
          type: integer
          format: int64
        gross_sum:
          type: number
          format: double
        verdict:
          type: string
          enum:
            - GOOD
            - THIN
            - NON_LINEAR
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key created via /api-key/create

````