> ## 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. # Create evaluation > Start a new evaluation for a completed run **Async operation**: This endpoint returns immediately with an evaluation ID. Poll `GET /api/dataframer/evaluations/{evaluation_id}/` until status is `COMPLETED` or `FAILED`. The run must be in `SUCCEEDED` status before an evaluation can be created. ## OpenAPI ````yaml POST /api/dataframer/evaluations/ 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/: post: summary: Create evaluation description: >- Start a new evaluation for a completed run. **Async operation**: This endpoint returns immediately with an evaluation ID. Poll `GET /api/dataframer/evaluations/{evaluation_id}/` until status is `SUCCEEDED` or `FAILED`. The run must be in `SUCCEEDED` status before an evaluation can be created. operationId: api_dataframer_evaluations_create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EvaluationCreate' examples: default_model: summary: Use default model value: run_id: a98715da-921d-4326-bbf8-208f8bcc2956 custom_model: summary: Specify evaluation model value: run_id: a98715da-921d-4326-bbf8-208f8bcc2956 evaluation_model: anthropic/claude-sonnet-5 responses: '202': description: Evaluation started successfully content: application/json: schema: $ref: '#/components/schemas/Evaluation' '400': description: Bad request content: application/json: schema: type: object properties: run_id: type: array items: type: string example: - This field is required. evaluation_model: type: array items: type: string example: - 'Unsupported evaluation model: invalid-model' error: type: string example: Can only evaluate completed runs '401': description: Authentication credentials were not provided '402': description: Payment required - subscription inactive '404': description: Run 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.create( run_id="a98715da-921d-4326-bbf8-208f8bcc2956", ) print(evaluation.id) - lang: cURL source: |- curl https://df-api.dataframer.ai/api/dataframer/evaluations/ \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $DATAFRAMER_API_KEY" \ -d '{ "run_id": "a98715da-921d-4326-bbf8-208f8bcc2956" }' components: schemas: EvaluationCreate: type: object description: Request body for creating an evaluation required: - run_id properties: run_id: type: string format: uuid description: >- ID of the completed run to evaluate. Run must be in SUCCEEDED status. evaluation_model: type: string description: >- AI model to use for evaluation. Defaults to anthropic/claude-sonnet-5-thinking. enum: - anthropic/claude-fable-5-1-thinking - anthropic/claude-opus-5-5-thinking - anthropic/claude-sonnet-5-5-thinking - openai/gpt-6-astra - openai/gpt-6-astra-thinking - openai/gpt-6.1-sol - openai/gpt-6.1-sol-thinking - openai/gpt-5.6-terra - openai/gpt-5.6-terra-thinking - databricks/system.ai.claude-sonnet-5 - databricks/system.ai.claude-sonnet-5-thinking - databricks/system.ai.claude-opus-5 - databricks/system.ai.claude-opus-5-thinking - databricks/system.ai.gpt-6-astra - databricks/system.ai.gpt-6-astra-thinking - databricks/system.ai.gpt-6-1-sol - databricks/system.ai.gpt-6-1-sol-thinking - databricks/system.ai.gpt-5-6-terra - databricks/system.ai.gpt-5-6-terra-thinking default: anthropic/claude-sonnet-5-5-thinking 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.