> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataframer.ai/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: []
tags:
  - name: Seed Datasets
    description: Manage seed datasets for generation
  - name: Specs
    description: Data specifications for sample generation
  - name: Runs
    description: Generation runs and results
  - name: Evaluations
    description: Evaluate generated sample quality
  - name: Red Teaming
    description: Security testing and adversarial prompts
  - name: Spec Creation
    description: Create specs from datasets or from scratch (seedless)
  - name: Generation
    description: Synthetic data generation
  - name: API Keys
    description: API key management and rotation
  - name: Health
    description: Health check endpoints
  - name: Models
    description: Available AI models
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:
      tags:
        - Evaluations
      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:

        - **conformance_score**: Overall score (0-100) measuring how well
        samples match expected distributions

        - **conformance_explanation**: Human-readable explanation of the
        conformance score and notable deviations

        - **distribution_analysis**: Per-property comparison of expected vs
        observed percentages

        - **sample_classifications**: How each generated sample was classified
        for each property
      operationId: api_dataframer_evaluations_read
      responses:
        '200':
          description: Evaluation details
          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
                    conformance_score: 85.5
                    conformance_explanation: >-
                      Generated samples largely conform to the spec with minor
                      deviations in distribution.
                    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'
                    started_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'
                    duration_seconds: 60
                pending_evaluation:
                  summary: Evaluation in progress
                  value:
                    id: 024319ff-7534-4f26-ba80-e540af493863
                    run_id: a98715da-921d-4326-bbf8-208f8bcc2956
                    status: PENDING
                    conformance_score: null
                    conformance_explanation: null
                    distribution_analysis: null
                    sample_classifications: []
                    started_at: null
                    completed_at: null
                    error_message: null
                    created_by_email: user@example.com
                    created_at: '2025-01-15T10:30:00Z'
                    duration_seconds: null
        '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: JavaScript
          source: |-
            import Dataframer from 'dataframer';

            const client = new Dataframer({
              apiKey: process.env['DATAFRAMER_API_KEY'], // This is the default and can be omitted
            });

            const evaluation = await client.dataframer.evaluations.retrieve(
              '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
            );

            console.log(evaluation.id);
        - 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)
components:
  schemas:
    Evaluation:
      type: object
      description: >-
        Full evaluation details including distribution analysis and sample
        classifications
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique identifier for the evaluation
        run_id:
          type: string
          format: uuid
          readOnly: true
          description: ID of the run being evaluated
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - SUCCEEDED
            - FAILED
          description: Current status of the evaluation
        conformance_score:
          type: number
          nullable: true
          description: >-
            Overall conformance score (0-100) measuring how well generated
            samples match the spec's expected distributions. Null until
            evaluation completes.
        conformance_explanation:
          type: string
          nullable: true
          description: >-
            Human-readable explanation of the conformance score and any notable
            deviations
        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
          readOnly: true
          description: >-
            Classification results for each generated sample. Empty until
            evaluation completes.
          items:
            $ref: '#/components/schemas/SampleClassification'
        started_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          description: When evaluation processing started
        completed_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          description: When evaluation completed
        error_message:
          type: string
          nullable: true
          readOnly: true
          description: Error message if evaluation failed
        created_by_email:
          type: string
          readOnly: true
          description: Email of the user who created the evaluation
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When the evaluation was created
        duration_seconds:
          type: number
          nullable: true
          readOnly: true
          description: Time taken to complete the evaluation in seconds
        company_id:
          type: string
          format: uuid
          readOnly: true
          description: ID of the company that owns this evaluation
        status_display:
          type: string
          readOnly: true
          description: Human-readable status display
        conformant_areas:
          type: string
          nullable: true
          readOnly: true
          description: Description of areas where samples conform well to the spec
        non_conformant_areas:
          type: string
          nullable: true
          readOnly: true
          description: Description of areas where samples deviate from the spec
        trace:
          type: object
          nullable: true
          readOnly: true
          description: >-
            Internal trace information including task_id and evaluation model
            used
          additionalProperties: true
        created_by:
          type: integer
          readOnly: true
          description: ID of the user who created this evaluation
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: When the evaluation was last updated
    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
        observed_distributions:
          type: object
          description: Deprecated alias for evaluated_distributions
          additionalProperties:
            type: number
        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
          readOnly: true
          description: Unique identifier for this classification
        evaluation_id:
          type: string
          format: uuid
          readOnly: true
          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
          readOnly: true
          description: When this classification was created
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key authentication. Format: "Bearer YOUR_API_KEY"'

````