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

# Get Candidate Benchmark

> Get anchor-balanced candidate-level benchmark analytics.



## OpenAPI

````yaml /openapi.json get /v1/experiments/{experiment_id}/candidate-benchmark
openapi: 3.1.0
info:
  description: Customer-owned evaluation lifecycle API.
  title: HeyBee Public API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.heybee.app
security: []
paths:
  /v1/experiments/{experiment_id}/candidate-benchmark:
    get:
      tags:
        - Analytics
      summary: Get Candidate Benchmark
      description: Get anchor-balanced candidate-level benchmark analytics.
      operationId: >-
        get_candidate_benchmark_v1_experiments__experiment_id__candidate_benchmark_get
      parameters:
        - in: path
          name: experiment_id
          required: true
          schema:
            format: uuid
            title: Experiment Id
            type: string
        - in: header
          name: authorization
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - in: header
          name: X-API-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateBenchmarkResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
components:
  schemas:
    CandidateBenchmarkResponse:
      description: Benchmark-only candidate-level aggregate analytics.
      properties:
        aggregation_policy:
          title: Aggregation Policy
          type: string
        analysis_available:
          title: Analysis Available
          type: boolean
        candidates:
          items:
            $ref: '#/components/schemas/CandidateBenchmarkRowResponse'
          title: Candidates
          type: array
        computed_at:
          format: date-time
          title: Computed At
          type: string
        issues:
          items:
            $ref: '#/components/schemas/CandidateBenchmarkIssueResponse'
          title: Issues
          type: array
        pairwise_matrix:
          items:
            $ref: '#/components/schemas/CandidateBenchmarkPairwiseMatrixRowResponse'
          title: Pairwise Matrix
          type: array
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        summary:
          anyOf:
            - $ref: '#/components/schemas/CandidateBenchmarkSummaryResponse'
            - type: 'null'
      required:
        - analysis_available
        - computed_at
        - aggregation_policy
      title: CandidateBenchmarkResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    CandidateBenchmarkRowResponse:
      description: Aggregate benchmark metrics for one candidate.
      properties:
        aggregate_rank:
          title: Aggregate Rank
          type: integer
        aggregate_score:
          title: Aggregate Score
          type: number
        anchor_win_rate:
          title: Anchor Win Rate
          type: number
        candidate_id:
          format: uuid
          title: Candidate Id
          type: string
        candidate_key:
          title: Candidate Key
          type: string
        candidate_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Candidate Label
        eligible_anchor_count:
          title: Eligible Anchor Count
          type: integer
        runner_up_count:
          title: Runner Up Count
          type: integer
        top_finish_count:
          title: Top Finish Count
          type: integer
      required:
        - candidate_id
        - candidate_key
        - aggregate_score
        - aggregate_rank
        - eligible_anchor_count
        - anchor_win_rate
        - top_finish_count
        - runner_up_count
      title: CandidateBenchmarkRowResponse
      type: object
    CandidateBenchmarkIssueResponse:
      description: Aggregation issue that excluded an anchor/candidate cell.
      properties:
        anchor_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Anchor Id
        anchor_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Anchor Value
        candidate_id:
          format: uuid
          title: Candidate Id
          type: string
        candidate_key:
          title: Candidate Key
          type: string
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
        - candidate_id
        - candidate_key
        - code
        - message
      title: CandidateBenchmarkIssueResponse
      type: object
    CandidateBenchmarkPairwiseMatrixRowResponse:
      description: Anchor-balanced head-to-head summary between two candidates.
      properties:
        anchor_wins_a:
          title: Anchor Wins A
          type: number
        anchor_wins_b:
          title: Anchor Wins B
          type: number
        candidate_a_id:
          format: uuid
          title: Candidate A Id
          type: string
        candidate_a_key:
          title: Candidate A Key
          type: string
        candidate_a_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Candidate A Label
        candidate_b_id:
          format: uuid
          title: Candidate B Id
          type: string
        candidate_b_key:
          title: Candidate B Key
          type: string
        candidate_b_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Candidate B Label
        comparable_anchor_count:
          title: Comparable Anchor Count
          type: integer
        ties:
          title: Ties
          type: number
      required:
        - candidate_a_id
        - candidate_a_key
        - candidate_b_id
        - candidate_b_key
        - comparable_anchor_count
        - anchor_wins_a
        - anchor_wins_b
        - ties
      title: CandidateBenchmarkPairwiseMatrixRowResponse
      type: object
    CandidateBenchmarkSummaryResponse:
      description: Top-level decision summary for benchmark candidate aggregation.
      properties:
        ambiguous_cell_count:
          title: Ambiguous Cell Count
          type: integer
        confidence_inputs:
          $ref: '#/components/schemas/CandidateBenchmarkConfidenceInputsResponse'
        decision_status:
          title: Decision Status
          type: string
        eligible_anchor_count:
          title: Eligible Anchor Count
          type: integer
        total_anchor_count:
          title: Total Anchor Count
          type: integer
        winner_candidate_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Winner Candidate Id
        winner_candidate_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Winner Candidate Key
        winner_candidate_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Winner Candidate Label
      required:
        - decision_status
        - eligible_anchor_count
        - total_anchor_count
        - ambiguous_cell_count
        - confidence_inputs
      title: CandidateBenchmarkSummaryResponse
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    CandidateBenchmarkConfidenceInputsResponse:
      description: Inputs used to decide whether a candidate winner can be declared.
      properties:
        experiment_confidence:
          title: Experiment Confidence
          type: number
        runner_up_head_to_head_anchor_win_rate:
          title: Runner Up Head To Head Anchor Win Rate
          type: number
        top_margin:
          title: Top Margin
          type: number
      required:
        - experiment_confidence
        - top_margin
        - runner_up_head_to_head_anchor_win_rate
      title: CandidateBenchmarkConfidenceInputsResponse
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: Supabase JWT
      scheme: bearer
      type: http
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey

````