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

# List immutable benchmark evidence for homology search policies

> Returns one cursor page of frozen benchmark evidence, filterable by release, semantic profile, search policy, or target space. Each entry states the benchmark and baseline it measured, how many queries and independent homology groups it covers, and its promotion decision. Evaluation evidence is scoped to a benchmark, never to an individual query or an individual returned hit.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/homology/search-evaluations
openapi: 3.1.0
info:
  description: >-
    Deterministic biological evidence primitives. Every response is the same
    envelope: ok, data, warnings, provenance.
  title: Rafflesia API
  version: 0.1.0
servers:
  - description: Production
    url: https://api.rafflesia.ai
security:
  - bearerAuth: []
paths:
  /v1/homology/search-evaluations:
    get:
      tags:
        - Homology
      summary: List immutable benchmark evidence for homology search policies
      description: >-
        Returns one cursor page of frozen benchmark evidence, filterable by
        release, semantic profile, search policy, or target space. Each entry
        states the benchmark and baseline it measured, how many queries and
        independent homology groups it covers, and its promotion decision.
        Evaluation evidence is scoped to a benchmark, never to an individual
        query or an individual returned hit.
      operationId: homology_search_evaluations_list
      parameters:
        - description: Optional immutable release filter.
          explode: false
          in: query
          name: database_release_id
          schema:
            description: Optional immutable release filter.
            type: string
        - description: Optional hprof_ semantic-profile filter.
          explode: false
          in: query
          name: semantic_profile_id
          schema:
            description: Optional hprof_ semantic-profile filter.
            type: string
        - description: Optional immutable search-policy filter.
          explode: false
          in: query
          name: search_policy_id
          schema:
            description: Optional immutable search-policy filter.
            type: string
        - description: Optional exact htsp_ target-space filter.
          explode: false
          in: query
          name: target_space_id
          schema:
            description: Optional exact htsp_ target-space filter.
            type: string
        - explode: false
          in: query
          name: limit
          schema:
            default: 20
            format: int64
            maximum: 100
            minimum: 1
            type: integer
        - explode: false
          in: query
          name: starting_after
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopeHomologySearchEvaluationList'
          description: OK
          headers:
            Rafflesia-Contract-Digest:
              schema:
                type: string
            Rafflesia-Version:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
components:
  schemas:
    EnvelopeHomologySearchEvaluationList:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - >-
              https://example.com/schemas/EnvelopeHomologySearchEvaluationList.json
          format: uri
          readOnly: true
          type: string
        data:
          $ref: '#/components/schemas/HomologySearchEvaluationList'
          description: Operation result data.
        error:
          $ref: '#/components/schemas/APIError'
          description: Structured error information.
        evidence:
          $ref: '#/components/schemas/EvidenceSummary'
          description: Mechanical evidence summary for agent inspection and chaining.
        ok:
          description: Whether the operation succeeded.
          type: boolean
        provenance:
          $ref: '#/components/schemas/Provenance'
          description: Execution provenance.
        warnings:
          description: Non-fatal warnings.
          items:
            $ref: '#/components/schemas/Warning'
          type:
            - array
            - 'null'
      required:
        - ok
        - warnings
        - provenance
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://example.com/schemas/ErrorModel.json
          format: uri
          readOnly: true
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    HomologySearchEvaluationList:
      additionalProperties: false
      properties:
        data:
          items:
            $ref: '#/components/schemas/HomologySearchEvaluation'
          type:
            - array
            - 'null'
        has_more:
          type: boolean
        next_cursor:
          type: string
        object:
          enum:
            - list
          type: string
        url:
          type: string
      required:
        - object
        - url
        - data
        - has_more
      type: object
    APIError:
      additionalProperties: false
      properties:
        code:
          description: Stable specific error code.
          type: string
        details:
          additionalProperties: {}
          description: Additional structured error details.
          type: object
        doc_url:
          description: Stable documentation URL for this error code.
          type: string
        message:
          description: Human-readable error message.
          type: string
        param:
          description: Request field responsible for the error when known.
          type: string
        type:
          description: Stable coarse error category.
          enum:
            - invalid_request_error
            - resource_missing
            - resource_expired
            - conflict_error
            - rate_limit_error
            - authentication_error
            - permission_error
            - billing_error
            - api_error
          type: string
      required:
        - type
        - code
        - message
        - doc_url
      type: object
    EvidenceSummary:
      additionalProperties: false
      properties:
        duration_ms:
          description: >-
            Primary elapsed duration in milliseconds when the response exposes
            one.
          format: int64
          type: integer
        input_refs:
          description: >-
            Input references detected from request fields such as object_id,
            structure_id, target_id, and sequence_id.
          items:
            type: string
          type:
            - array
            - 'null'
        object_refs:
          description: Object ids or object refs visible in the response/provenance.
          items:
            type: string
          type:
            - array
            - 'null'
        output_refs:
          description: Output references detected from response data and generated objects.
          items:
            type: string
          type:
            - array
            - 'null'
        row_count:
          description: >-
            Primary row count or returned row count when the response exposes
            one.
          format: int64
          type: integer
        warnings_count:
          description: Number of non-fatal warnings in the envelope.
          format: int64
          type: integer
      required:
        - warnings_count
      type: object
    Provenance:
      additionalProperties: false
      properties:
        cache_hit:
          description: Whether cached output was reused.
          type: boolean
        created_at:
          description: UTC timestamp.
          type: string
        database_snapshots:
          description: Database snapshots used.
          items:
            $ref: '#/components/schemas/DatabaseSnapshot'
          type:
            - array
            - 'null'
        generated_object_ids:
          description: Object ids created by the operation.
          items:
            type: string
          type:
            - array
            - 'null'
        input_hash:
          description: SHA-256 hash of canonical request input.
          type: string
        operation:
          description: Primitive operation id.
          type: string
        parameters_hash:
          description: SHA-256 hash of parameters.
          type: string
        request_id:
          description: Unique request identifier.
          type: string
        server_version:
          description: Server version.
          type: string
        tool_versions:
          description: Tool versions used.
          items:
            $ref: '#/components/schemas/ToolVersion'
          type:
            - array
            - 'null'
      required:
        - request_id
        - operation
        - created_at
        - server_version
      type: object
    Warning:
      additionalProperties: false
      properties:
        code:
          description: Stable warning code.
          type: string
        details:
          additionalProperties: {}
          description: Additional structured warning details.
          type: object
        message:
          description: Human-readable warning message.
          type: string
      required:
        - code
        - message
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    HomologySearchEvaluation:
      additionalProperties: false
      properties:
        baseline_id:
          type: string
        benchmark_id:
          type: string
        canonical_filter_sha256:
          type: string
        database_release_ids:
          items:
            type: string
          type:
            - array
            - 'null'
        decision:
          enum:
            - promoted
            - observational
            - not_promoted
          type: string
        filter_distribution_class:
          enum:
            - uniform
            - clustered
            - adversarial
          type: string
        filter_selectivity_class:
          enum:
            - ultra_sparse
            - sparse
            - moderate
            - broad
            - all
          type: string
        group_manifest_sha256:
          type: string
        homology_group_count:
          format: int64
          type: integer
        id:
          pattern: ^heval_[0-9a-f]{64}$
          type: string
        is_per_query_confidence:
          description: >-
            Always false. Evaluation evidence is scoped to a frozen benchmark,
            never an individual query.
          type: boolean
        measurements:
          items:
            $ref: '#/components/schemas/HomologySearchEvaluationMeasurement'
          type:
            - array
            - 'null'
        object:
          enum:
            - homology_search_evaluation
          type: string
        query_count:
          format: int64
          type: integer
        search_policy_contract_id:
          pattern: ^hpcon_[0-9a-f]{64}$
          type: string
        search_policy_id:
          type: string
        semantic_profile_id:
          pattern: ^hprof_[0-9a-f]{64}$
          type: string
        sha256:
          type: string
        target_space_id:
          pattern: ^htsp_[0-9a-f]{64}$
          type: string
      required:
        - id
        - object
        - sha256
        - database_release_ids
        - semantic_profile_id
        - search_policy_id
        - search_policy_contract_id
        - benchmark_id
        - baseline_id
        - group_manifest_sha256
        - query_count
        - homology_group_count
        - decision
        - measurements
        - is_per_query_confidence
      type: object
    DatabaseSnapshot:
      additionalProperties: false
      properties:
        digest:
          type: string
        kind:
          type: string
        name:
          type: string
        version:
          type: string
      required:
        - name
        - version
      type: object
    ToolVersion:
      additionalProperties: false
      properties:
        name:
          type: string
        path:
          type: string
        version:
          type: string
      required:
        - name
        - version
      type: object
    HomologySearchEvaluationMeasurement:
      additionalProperties: false
      properties:
        name:
          type: string
        scope:
          type: string
        unit:
          type: string
        value:
          format: double
          type: number
      required:
        - name
        - value
        - unit
        - scope
      type: object
  securitySchemes:
    bearerAuth:
      description: 'A Rafflesia API key, sent as `Authorization: Bearer <key>`.'
      scheme: bearer
      type: http

````