---
title: "Evaluate datasets with specified metrics"
method: POST
path: "/evaluate"
---

# Evaluate datasets with specified metrics

`POST /evaluate`

## Request body

- object
  - `synthetic_data_id` string — ID of synthetic dataset to evaluate (either this or seed_data_id is required)
  - `seed_data_id` string — ID of seed dataset to evaluate (either this or synthetic_data_id is required)
  - `metrics_id` string — ID of metrics to use for evaluation (will use latest if not provided)
  - `pair_query` object — Optional query parameters to filter dataset pairs
    - `latest_n_pairs` integer — Maximum number of latest pairs to include (defaults to 150 if not provided)
    - `pair_labels` string[] — Filter pairs by labels (optional)
    - `last_n_seconds` integer — Filter pairs created in the last N seconds (optional)

## Response `200`

Evaluation successfully completed

- object
  - `eval_results_id` string
  - `dataset_id` string
  - `created_at` string
  - `scores` object[]
    - `metric` string
    - `mean_score` number
    - `std_dev` number
    - `ci_low` number
    - `ci_high` number
    - `ci_confidence` number
    - `median_score` number
    - `min_score` number
    - `max_score` number
    - `lowest_scoring_pairs` object[]
      - `pair_id` string
      - `score_reason` string
  - `pair_count` integer

## Other responses

- `403` — Forbidden - dataset size exceeds plan limit
- `500` — Internal server error

## Changes

- **2026-07-13** `f332cf4d71d4` — 1 warning, 1 info
  - removed the request property `pair_query/pair_label`
  - added the new optional request property `pair_query/pair_labels`
- **2025-07-03** `a9fca2bc07fe` — 1 info
  - removed the non-success response with the status `400`
- **2025-07-03** `7a3463d3306a` — 4 info
  - added the new optional request property `pair_query/last_n_seconds`
  - added the non-success response with the status `400`
  - added the non-success response with the status `403`
  - added the non-success response with the status `500`
- **2025-06-10** `d550ab79ee7e` — 8 info
  - added the new optional request property `pair_query`
  - added the new optional request property `synthetic_data_id`
  - the request property `metrics_id` became optional
  - the request property `seed_data_id` became optional
  - …4 more
- **2025-04-30** `2eb8cb01b88b` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/getplumai/apis/plum-api/changes/evaluate/post.md)

---

[API](https://skmtc.dev/getplumai/apis/plum-api.md) · [All operations](https://skmtc.dev/getplumai/apis/plum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getplumai/plum-api/revisions/f332cf4d71d4/schema)