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

# Get evaluation

> Retrieve full evaluation details including distribution analysis

Use this endpoint to poll for evaluation completion and retrieve results.

When an evaluation completes successfully, the response includes:

* **conformance\_score**: Overall score (0-100) measuring how well samples match expected distributions
* **distribution\_analysis**: Per-property comparison of expected vs observed percentages
* **sample\_classifications**: How each generated sample was classified for each property


## OpenAPI

````yaml GET /api/dataframer/evaluations/{evaluation_id}/
openapi: 3.0.0
info:
  title: DataFramer API
  version: 0.1.0
  description: ''
  termsOfService: https://www.aimon.ai/docs/privacy-policy.pdf
  contact:
    name: DataFramer Support
    email: info@dataframer.ai
  license:
    name: Proprietary
  x-logo:
    url: https://dataframer.ai/logo.png
    altText: DataFramer AI
  x-stainless:
    package-name: aimon-dataframer
    namespace:
      - aimon
      - dataframer
servers:
  - url: https://df-api.dataframer.ai
    description: Production server
security:
  - BearerAuth: []
externalDocs:
  description: Complete API Guide
  url: https://docs.dataframer.ai/dataframer
paths:
  /api/dataframer/evaluations/{evaluation_id}/:
    parameters:
      - name: evaluation_id
        in: path
        required: true
        description: Unique identifier of the evaluation
        schema:
          type: string
          format: uuid
    get:
      summary: Get evaluation
      description: >-
        Retrieve full evaluation details including distribution analysis.


        Also use this endpoint to poll for evaluation completion while it is
        still PROCESSING.


        When an evaluation completes successfully, the response includes:

        - **distribution_analysis**: Per-property comparison of requested,
        expected, and evaluated percentages

        - **sample_classifications**: How each generated sample was classified
        for each property
      operationId: api_dataframer_evaluations_read
      responses:
        '200':
          description: >-
            Evaluation details, including distribution analysis and sample
            classifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluation'
              examples:
                completed_evaluation:
                  summary: Completed evaluation with results
                  value:
                    id: f4e64db3-3cac-4706-9fd0-c6695ae4694a
                    run_id: a98715da-921d-4326-bbf8-208f8bcc2956
                    status: SUCCEEDED
                    distribution_analysis:
                      - property_name: sentiment
                        total_samples: 100
                        requested_distributions:
                          positive: 40
                          negative: 30
                          neutral: 30
                        expected_distributions:
                          positive: 42
                          negative: 30
                          neutral: 28
                        evaluated_distributions:
                          positive: 45
                          negative: 28
                          neutral: 27
                        total_samples_analyzed: 100
                    sample_classifications:
                      - id: ad7913d9-a0aa-4a80-83a7-70026e3c1f1d
                        evaluation_id: f4e64db3-3cac-4706-9fd0-c6695ae4694a
                        sample_identifier: sample_1
                        classifications:
                          sentiment: positive
                          topic: technology
                        created_at: '2025-01-15T10:30:00Z'
                    completed_at: '2025-01-15T10:31:00Z'
                    error_message: null
                    created_by_email: user@example.com
                    created_at: '2025-01-15T10:30:00Z'
                pending_evaluation:
                  summary: Evaluation in progress
                  value:
                    id: 024319ff-7534-4f26-ba80-e540af493863
                    run_id: a98715da-921d-4326-bbf8-208f8bcc2956
                    status: PENDING
                    distribution_analysis: null
                    sample_classifications: []
                    completed_at: null
                    error_message: null
                    created_by_email: user@example.com
                    created_at: '2025-01-15T10:30:00Z'
        '400':
          description: Invalid UUID format
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      Invalid evaluation_id format: "invalid" is not a valid
                      UUID
        '401':
          description: Unauthorized
        '404':
          description: Evaluation not found
        '500':
          description: Internal server error
      x-codeSamples:
        - lang: Python
          source: |-
            import os
            from dataframer import Dataframer

            client = Dataframer(
                api_key=os.environ.get("DATAFRAMER_API_KEY"),  # This is the default and can be omitted
            )
            evaluation = client.dataframer.evaluations.retrieve(
                "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            )
            print(evaluation.id)
        - lang: cURL
          source: >-
            curl
            https://df-api.dataframer.ai/api/dataframer/evaluations/$EVALUATION_ID/
            \
                -H "Authorization: Bearer $DATAFRAMER_API_KEY"
components:
  schemas:
    Evaluation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the evaluation
        run_id:
          type: string
          format: uuid
          description: ID of the run being evaluated
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - SUCCEEDED
            - FAILED
          description: Current status of the evaluation
        distribution_analysis:
          type: array
          nullable: true
          description: >-
            Per-property comparison of expected vs observed distributions. Null
            until evaluation completes.
          items:
            $ref: '#/components/schemas/DistributionAnalysisItem'
        sample_classifications:
          type: array
          description: >-
            Classification results for each generated sample. Empty until
            evaluation completes.
          items:
            $ref: '#/components/schemas/SampleClassification'
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: When evaluation completed
        error_message:
          type: string
          nullable: true
          description: Error message if evaluation failed
        created_by_email:
          type: string
          description: Email of the user who created the evaluation
        created_at:
          type: string
          format: date-time
          description: When the evaluation was created
    DistributionAnalysisItem:
      type: object
      description: Distribution comparison for a single property
      properties:
        property_name:
          type: string
          description: Name of the property being analyzed
        total_samples:
          type: integer
          description: Total number of samples in the run
        requested_distributions:
          type: object
          description: Target percentage for each property value (from the spec)
          additionalProperties:
            type: number
          example:
            positive: 40
            negative: 30
            neutral: 30
        expected_distributions:
          type: object
          description: >-
            Percentage for each property value actually achievable given the
            sample count (from generation-time sampling)
          additionalProperties:
            type: number
          example:
            positive: 42
            negative: 30
            neutral: 28
        evaluated_distributions:
          type: object
          description: >-
            Percentage for each property value as classified by an LLM evaluator
            post-generation
          additionalProperties:
            type: number
          example:
            positive: 45
            negative: 28
            neutral: 27
        total_samples_analyzed:
          type: integer
          description: >-
            Number of samples that were successfully classified for this
            property
    SampleClassification:
      type: object
      description: Classification results for a single generated sample
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for this classification
        evaluation_id:
          type: string
          format: uuid
          description: ID of the parent evaluation
        sample_identifier:
          type: string
          description: >-
            Identifier for the sample (matches the generated sample name from
            the run)
        classifications:
          type: object
          description: Map of property names to their classified values for this sample
          additionalProperties:
            type: string
          example:
            sentiment: positive
            topic: technology
            length: medium
        created_at:
          type: string
          format: date-time
          description: When this classification was created
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key authentication. Format: "Bearer YOUR_API_KEY"'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.