---
title: "List Evals"
method: GET
path: "/v2/evals"
tags: ["Evals"]
---

# List Evals

`GET /v2/evals`

List all evals, with optional filtering.

Args:
    workspace_uuid (str, optional): Optional workspace UUID for filtering.
        Use "*" for enterprise-wide access, omit for user's current workspace.

Returns:
    list[Eval]: List of evals matching the filter.

Raises:
    AymaraAPIError: If the request is invalid.

Example:
    GET /api/evals?workspace_uuid=...

## Query parameters

- `workspace_uuid` string
- `limit` integer
- `offset` integer

## Response `200`

OK

- PagedEval
  - `items` Eval[], required
    - `eval_uuid` string, nullable — Unique identifier for the evaluation.
    - `name` string, nullable — Name of the evaluation.
    - `created_by` string, nullable — Name of the user who created the evaluation.
    - `ai_description` string, required — Description of the AI under evaluation.
    - `ai_instructions` union — Instructions the AI should follow. String for normal evals, AgentInstructions for single-agent evals, WorkflowInstructions for multi-agent workflows.
      - string
      - AgentInstructions
        - `agent_name` string, nullable
        - `system_prompt` string, required
        - `tools` union — Instructions for the agent, can be a string or a list/dict of tools.
          - ToolArray — Container for an array of tools
            - `type` 'array'
            - `value` Tool[], required
              - …
          - ToolDict — Container for a tool dictionary
            - `type` 'dict'
            - `value` object, required
          - ToolString — Container for string-based tool instructions
            - `type` 'string'
            - `value` string, required
      - WorkflowInstructions — Workflow instructions for multi-agent workflows.
        - `instructions` AgentInstructions[], required — List of agent instructions for the workflow. Must contain at least one agent.
          - `agent_name` string, nullable
          - `system_prompt` string, required
          - `tools` union — Instructions for the agent, can be a string or a list/dict of tools.
            - ToolArray — Container for an array of tools
              - …
            - ToolDict — Container for a tool dictionary
              - …
            - ToolString — Container for string-based tool instructions
              - …
    - `eval_type` string, required — Type of the eval (safety, accuracy, etc.)
    - `eval_instructions` string, nullable — Additional instructions for the eval, if any.
    - `language` string, nullable — Language code for the eval (default: "en").
    - `modality` 'text' | 'image' | 'video' — Content type for AI interactions.
    - `ground_truth` union — Ground truth data or reference file, if any.
      - string
      - FileReference — Reference to a file, either by file_uuid (preferred) or legacy remote_file_path. When file_uuid is provided, the system will look up the File record and use its remote_file_path. The remote_file_path field is maintained for backwards compatibility.
        - `file_uuid` string, nullable
        - `remote_file_path` string, nullable
    - `num_prompts` integer, nullable — Number of prompts/questions in the eval (default: 50).
    - `prompt_examples` PromptExample[], nullable — List of example prompts for the eval.
      - `content` string, required — Content of the example prompt.
      - `example_uuid` string, nullable — Unique identifier for the example, if any.
      - `type` 'good' | 'bad'
      - `explanation` string, nullable — Explanation for the example, if any.
    - `is_jailbreak` boolean — Indicates if the eval is a jailbreak test.
    - `is_sandbox` boolean — Indicates if the eval results are sandboxed.
    - `workspace_uuid` string, nullable — UUID of the associated workspace, if any.
    - `status` 'created' | 'processing' | 'finished' | 'failed' — Resource status.
    - `created_at` string, date-time, nullable — Timestamp when the eval was created.
    - `updated_at` string, date-time, nullable — Timestamp when the eval was last updated.
  - `count` integer, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/aymara-ai/apis/aymara-api.md) · [All operations](https://skmtc.net/aymara-ai/apis/aymara-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aymara-ai/aymara-api/versions/0cb64ef11adf/schema)