---
title: "List User Evaluations"
method: GET
path: "/api/v3/evaluations/list"
tags: ["Evaluations"]
---

# List User Evaluations

`GET /api/v3/evaluations/list`

## Request

- Base URL: `https://api.nugen.in`
- URL: `https://api.nugen.in/api/v3/evaluations/list`
- Auth: HTTP bearer

Retrieve all evaluations for the authenticated user.

This endpoint returns a paginated list of lean evaluation rows. Fetch `GET /evaluations/{evaluation_id}` for the full record and `/results` for scores.

**Query Parameters:**

- `status` (optional): Filter by evaluation status (`QUEUED`, `PROCESSING`, `READY`, `FAILED`)
- `model_id` (optional): Filter by specific model ID
- `limit` (optional): Number of evaluations to return (1-100, default: 10)
- `offset` (optional): Number of evaluations to skip for pagination (default: 0)

**Returns:**

- `user_id`: The authenticated user's ID
- `evaluations`: List of `evaluation_id`, `evaluation_name`, `status`, `created_at`
- `total`: Total number of evaluations matching the filters
- `limit`: Requested page size
- `offset`: Current pagination offset

**Example Request:**

```json
GET /api/v3/evaluations/list?status=READY&limit=5&offset=0
Headers: {"Authorization": "Bearer <api_key>"}
```

**Example Response:**

```json
{
  "user_id": "01KKBERWEEM634BQW9BK6Y0Y",
  "evaluations": [
    {
      "evaluation_id": "eval_01KKJHBNFY9STH1C9",
      "evaluation_name": "Clause Review v2 Eval",
      "status": "READY",
      "created_at": "2026-03-10T10:43:12.826791",
      "alignment_id": "alignment_01k4x9m2p7q3r8c1"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```

## Query parameters

- `status` string, nullable: Filter by evaluation status
- `model_id` string, nullable: Filter by model ID
- `limit` integer: Number of evaluations to return
- `offset` integer: Number of evaluations to skip

## Response `200`

Returns a list of all evaluations created by the user, with optional filtering by status or model ID. This endpoint allows users to retrieve their evaluation history, filter evaluations by status (e.g., PROCESSING, READY) or specific model, and supports pagination for easy navigation through large numbers of evaluations.

- EvaluationListResponse: The caller's evaluations.
  - `user_id` string, required: ID of the user
  - `evaluations` EvaluationListItem[], required: List of evaluations for the user
    - `evaluation_id` string, required: Unique identifier of the evaluation.
    - `evaluation_name` string, nullable: Display name of the evaluation.
    - `status` 'QUEUED' | 'PROCESSING' | 'READY' | 'FAILED' | 'STOPPED', required: 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
    - `created_at` string, date-time, required: Creation timestamp.
    - `alignment_id` string, nullable: Alignment project ID that produced the evaluated model. Null for base-model evaluations.
    - `results` object, nullable: Null until READY. model_id and metrics are the evaluated model's own scores. baseline_model_id and baseline_metrics are set only in comparison mode. comparison.metrics_relative is each metric's delta, evaluated minus baseline.
  - `total` integer, required: Total number of evaluations
  - `limit` integer, required: Limit used for pagination
  - `offset` integer, required: Offset used for pagination

## 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)