> ## 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 Next Pair > Get the next pair of samples to compare. - Auth: Supabase JWT only. API keys cannot reserve voting pairs. - For anchored experiments: if anchor_value is omitted, the controller selects the best available pair across *all* anchors (never a random anchor pick). ## OpenAPI ````yaml /openapi.json get /v1/experiments/{experiment_id}/next-pair 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}/next-pair: get: tags: - Voting summary: Get Next Pair description: >- Get the next pair of samples to compare. - Auth: Supabase JWT only. API keys cannot reserve voting pairs. - For anchored experiments: if anchor_value is omitted, the controller selects the best available pair across *all* anchors (never a random anchor pick). operationId: get_next_pair_v1_experiments__experiment_id__next_pair_get parameters: - in: path name: experiment_id required: true schema: format: uuid title: Experiment Id type: string - description: (Optional) restrict to a specific anchor value in: query name: anchor_value required: false schema: anyOf: - type: string - type: 'null' description: (Optional) restrict to a specific anchor value title: Anchor Value - description: Use policy-based pair selection before random fallback in: query name: use_thompson required: false schema: default: true description: Use policy-based pair selection before random fallback title: Use Thompson type: boolean - in: query name: prefetch_count required: false schema: default: 0 maximum: 1 minimum: 0 title: Prefetch Count type: integer - in: header name: authorization required: false schema: anyOf: - type: string - type: 'null' title: Authorization responses: '200': content: application/json: schema: $ref: '#/components/schemas/NextPairResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - BearerAuth: [] components: schemas: NextPairResponse: description: Response with the next pair to compare. properties: allow_playback_speed: default: false description: Whether audio voters may adjust playback speed title: Allow Playback Speed type: boolean anchor: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured anchor context for display title: Anchor anchor_value: anyOf: - type: string - type: 'null' description: The anchor value both samples share (if anchored experiment) title: Anchor Value axes: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' description: >- Voting axes [{axis_key,label,description}] for a multi-axis experiment; None/empty => single default A/B. title: Axes eligibility_policy_version: anyOf: - type: string - type: 'null' description: Eligibility policy version used to validate this pair title: Eligibility Policy Version enforce_playback: default: false description: Whether both-output playback thresholds are enforced for audio votes title: Enforce Playback type: boolean is_exam: default: false description: True if this pair is an exam pair (quality control) title: Is Exam type: boolean login_required: default: false description: >- True when the current participant is linked to an account and must log in. title: Login Required type: boolean min_playback_percent: default: 0 description: Required playback percentage for each audio output maximum: 100 minimum: 0 title: Min Playback Percent type: integer min_viewing_seconds: default: 0 description: Minimum viewing time (seconds) before voting is accepted minimum: 0 title: Min Viewing Seconds type: integer pair_id: description: Current sticky pair ID (required for vote binding) format: uuid title: Pair Id type: string participant_label: anyOf: - type: string - type: 'null' description: Short non-sensitive anonymous participant label. title: Participant Label participant_mode: anyOf: - enum: - anonymous - transferred - authenticated - linked_requires_login type: string - type: 'null' description: Current public voting participant mode. title: Participant Mode participant_required: default: false description: >- True when an anonymous voter must choose start-new or continue before a pair can be served. title: Participant Required type: boolean prefetch: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' description: Optional hydrated upcoming pairs for client-side media warming title: Prefetch remaining_comparisons: default: 0 description: Remaining comparisons in the experiment pool minimum: 0 title: Remaining Comparisons type: integer require_feedback: default: true description: Whether vote feedback is required for this experiment title: Require Feedback type: boolean sample_a: additionalProperties: true description: First sample to compare title: Sample A type: object sample_b: additionalProperties: true description: Second sample to compare title: Sample B type: object selection_components: anyOf: - additionalProperties: true type: object - type: 'null' description: Optional pair-selection diagnostics title: Selection Components selection_policy: anyOf: - type: string - type: 'null' description: Pair selection policy identifier used for this pair title: Selection Policy selection_score: anyOf: - type: number - type: 'null' description: Selection utility score for this pair title: Selection Score submit_ready: default: true description: True when this pair ID is already accepted by vote submission. title: Submit Ready type: boolean vote_cost_credits: default: 1 description: Credits required to vote this pair (0 for exam) minimum: 0 title: Vote Cost Credits type: integer required: - sample_a - sample_b - pair_id title: NextPairResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError 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 securitySchemes: BearerAuth: bearerFormat: Supabase JWT scheme: bearer type: http ````