---
title: "Create Benchmark"
method: POST
path: "/api/v3/benchmarks/create"
tags: ["Benchmarks"]
---

# Create Benchmark

`POST /api/v3/benchmarks/create`

## Request

- Base URL: `https://api.nugen.in`
- URL: `https://api.nugen.in/api/v3/benchmarks/create`
- Auth: HTTP bearer

Create a new benchmark generation run from documents.


This endpoint starts a benchmark generation run over the documents you name. The generated samplions can be used for model evaluation and testing.


**Request Body:**

- `document_ids`: List of document IDs to generate benchmarks from (required)
- `n_samples`: Number of benchmark samples to generate (required)
- `benchmark_name` (optional): Display name. Defaults to the benchmark id if omitted


**Returns:**

- `benchmark_id`: Unique identifier for tracking generation progress
- `status`: Initial status (always `QUEUED`)


**Raises:**

- `400`: If no documents provided
- `400`: If document validation fails (missing documents or unauthorized access)


**Example Request:**

```json
POST /api/v3/benchmarks/create
Headers: {"Authorization": "Bearer <api_key>"}

{
  "document_ids": ["document_01k4x9m2p7q3r5s8", "document_01k4x9m2p7q3r5sc", "document_01k4x9m2p7q3r5sd"],
  "n_samples": 10
}
```


**Example Response:**

```json
{
  "benchmark_id": "benchmark_01k4x9m2p7q3r6a1",
  "status": "QUEUED"
}
```


**Notes:**

- All document IDs are validated before creation to ensure they exist and belong to the user
- Use the returned benchmark_id with `/benchmarks/{id}/status` endpoint to track generation progress
- Once completed, the benchmark will be available for use in model evaluations

## Request body

- BenchmarkCreateRequest: Generate a benchmark from your documents.
  - `document_ids` string[], required: List of document IDs to generate benchmark from
  - `benchmark_name` string, nullable: Display name for the benchmark. Defaults to the benchmark id if omitted.
  - `n_samples` integer, nullable: Number of samples to generate (if None, decided from the content)

## Response `200`

Returns a unique identifier and initial status for the benchmark generation initiated from specified documents

- BenchmarkCreateResponse: Acknowledgement of a benchmark generation request.
  - `benchmark_id` string, required: Created benchmark identifier
  - `benchmark_name` string, required: Display name of the benchmark
  - `status` 'QUEUED' | 'PROCESSING' | 'READY' | 'FAILED' | 'STOPPED': Lifecycle status of a resource that runs asynchronously. Stored as is and returned as is, with no translation in between. - `QUEUED`: accepted and waiting for its workflow to start - `PROCESSING`: running - `READY`: finished successfully - `FAILED`: failed at any stage - `STOPPED`: stopped by the user before completion

## Other responses

- `401`: Invalid API key
- `403`: Authorization header missing or not a Bearer token
- `422`: Validation Error

---

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