---
title: "Preview metric"
method: POST
path: "/test_framework/v3/metrics/preview/"
tags: ["test_framework"]
---

# Preview metric

`POST /test_framework/v3/metrics/preview/`

## Request

- Base URL: `https://api.cekura.ai`
- URL: `https://api.cekura.ai/test_framework/v3/metrics/preview/`
- Auth: one of:
  - API key in header `X-CEKURA-API-KEY`
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Evaluate a metric configuration on up to 10 call logs or runs and return the verdicts, without saving the metric. Use it to check a metric before creating or updating it. Usually 30 seconds to 3 minutes; custom-code metrics can take longer.

## Request body

- MetricPreview
  - `agent_id` integer: Agent ID - all call logs/runs must belong to this agent
  - `project_id` integer: Project ID - all call logs/runs must belong to this project
  - `call_log_ids` integer[]: List of call log IDs to evaluate (maximum 10, required if run_ids not provided)
  - `run_ids` integer[]: List of run IDs to evaluate (maximum 10, required if call_log_ids not provided)
  - `metric_data` MetricPreviewData, required
    - `name` string, required: Name of the metric
    - `type` 'basic' | 'custom_prompt' | 'custom_code' | 'llm_judge', required: Type of metric: basic, custom_prompt, or custom_code * `basic` - Basic (Deprecated in favor of LLM Judge) * `custom_prompt` - Custom Prompt ( Deprecated in favor of LLM Judge) * `custom_code` - Custom Code * `llm_judge` - LLM Judge
    - `eval_type` 'binary' | 'continuous_qualitative' | 'numeric' | 'enum', required: Evaluation type: binary, continuous_qualitative, numeric, or enum. Legacy values (binary_workflow_adherence, binary_qualitative) are accepted and mapped to binary. * `binary` - Binary * `continuous_qualitative` - Continuous Qualitative * `numeric` - Numeric * `enum` - Enum
    - `evaluation_trigger` 'always' | 'automatic' | 'custom': When to trigger evaluation: always, automatic, or custom * `always` - Always * `automatic` - Automatic * `custom` - Custom
    - `trigger_type` 'llm_judge' | 'custom_code': Type of trigger evaluation: llm_judge or custom_code (only used when evaluation_trigger is custom) * `llm_judge` - LLM Judge * `custom_code` - Custom Code
    - `evaluation_trigger_prompt` string: Prompt for evaluation trigger (required for custom trigger with llm_judge)
    - `evaluation_trigger_custom_code` string: Python code for trigger evaluation (required for custom trigger with custom_code)
    - `configuration` unknown
    - `description` string: Description of what the metric measures (required for basic type)
    - `prompt` string: Custom prompt for evaluation (required for custom_prompt type)
    - `custom_code` string: Python code for custom evaluation (required for custom_code type)
    - `enum_values` string[]: List of possible enum values (required when eval_type is enum)
    - `audio_enabled` boolean: Whether the LLM judge must evaluate the source recording

## Response `200`

- object
  - `status` 'completed' | 'failed': `failed` when the job could not produce its result; see `error` / `errors`.
  - `project_id` integer, nullable
  - `agent_id` integer, nullable
  - `completed` integer: Items evaluated.
  - `total` integer
  - `results` object[]
    - `result` unknown
    - `score` number
    - `enum` string
    - `explanation` string
    - `is_relevant` boolean
    - `call_log_id` integer
    - `call_id` string, nullable
    - `run_id` integer
    - `error` string, nullable
  - `error` string, nullable: Why the job failed, when it did.

## Other responses

- `400`
- `403`: No access to the agent, project, metric or result the job runs on.
- `504`: The job did not finish within 15 minutes. It may still complete in the background.

## Changes

- **2026-11-03** `a6fb6a739212`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/test_framework/v3/metrics/preview/post.md)

---

[API](https://skmtc.dev/cekura/apis/cekura-api.md) - [All operations](https://skmtc.dev/cekura/apis/cekura-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cekura/apis/cekura-api/revisions/a6fb6a739212?raw)