---
title: "Create a new evaluation"
method: POST
path: "/evaluations"
tags: ["Evaluations"]
---

# Create a new evaluation

`POST /evaluations`

Creates and starts a new evaluation for a specific skill using a dataset and AI model

## Request body

- CreateEvaluationRequest — Request body for creating a new evaluation
  - `name` string, required — Name of the evaluation
  - `comment` string — Optional comment or description for the evaluation
  - `custom_instructions` string — Optional custom instructions for the AI model during evaluation
  - `dataset_id` string, required — ID of the dataset to use for evaluation
  - `model_id` string, required — ID of the AI model to use for evaluation
  - `skill_id` string, required — ID of the skill/bot to evaluate

## Response `200`

Evaluation successfully created and started

- CreateEvaluationResponse — Response after creating or restarting an evaluation
  - `evaluation` EvaluationDetails, required — Detailed evaluation object returned after creation or restart
    - `_id` string, required — Unique identifier for the evaluation
    - `name` string, required — Name of the evaluation
    - `data` object[] — Evaluation data (empty at creation)
    - `user_id` string, required — ID of the user who created the evaluation
    - `skill` object, required — Skill/bot being evaluated
      - `_id` string
      - `name` string
    - `dataset` object, required — Dataset used for evaluation
      - `_id` string
      - `name` string
    - `model` object, required — AI model used for evaluation
      - `_id` string
      - `name` string
      - `model_name` string
      - `provider` string
    - `status` 'in progress' | 'terminated' | 'pending' | 'failed', required — Current status of the evaluation
    - `progress` number, float, required — Completion progress (percentage)
    - `score` number, float, required — Current score (percentage)
    - `nb_questions` integer, required — Total number of questions
    - `is_child` boolean, required — Indicates if this is a restarted evaluation (child of original)
    - `comment` string — Comment or description
    - `custom_instructions` string — Custom instructions for the AI model
    - `createdAt` string, date-time, required — Creation timestamp
    - `updatedAt` string, date-time, required — Last update timestamp
    - `__v` integer — Version key
  - `message` string, required — Success message

## Other responses

- `400` — Invalid request - Missing required fields or invalid IDs
- `401` — Unauthorized - Invalid or missing authentication
- `404` — Resource not found - Invalid dataset_id, model_id, or skill_id
- `500` — Internal server error

---

[API](https://skmtc.net/smartly/apis/smartly-ai-apis.md) · [All operations](https://skmtc.net/smartly/apis/smartly-ai-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smartly/smartly-ai-apis/revisions/1e26909d86c9/schema)