> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Cancel Eval

> Cancel a pending or running eval

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.12](/release-notes/1.1.x#v1-1-12) or later of the Archetype platform.
</Callout>

## Overview

This endpoint cancels a pending or running eval and returns it in its `cancelled` state.

<Note>
  An eval that has already terminated (with `status` whose value is `completed`, `failed`, or
  `cancelled`) has nothing to cancel and returns HTTP status code `409`.
</Note>

Canceling is the prerequisite for deleting a non-terminal eval. Attempting to delete a
non-terminal eval fails, returning HTTP status `409`. Cancel the eval first to avoid this error.

## Request

<ParamField path="eval_id" type="string" required>
  Eval `evl_` id.
</ParamField>

## Response

Returns the cancelled eval, in the same format that [Get
Eval](/api-reference/agents/evals/get-eval) returns.

<ResponseField name="id" type="string" required>
  TypeID-encoded eval identifier (`evl_` prefix).
</ResponseField>

<ResponseField name="name" type="string" required>
  Human label for the eval.
</ResponseField>

<ResponseField name="org_id" type="string" required>
  Organization identifier the eval belongs to.
</ResponseField>

<ResponseField name="blueprint_id" type="string" required>
  The blueprint being evaluated.
</ResponseField>

<ResponseField name="primary" type="string" required>
  The run's headline, as `<target>.<objective>`.
</ResponseField>

<ResponseField name="examples" type="array" required>
  The examples the eval was created against, as resolved.
</ResponseField>

<ResponseField name="rendered_config" type="object" required>
  The fully-expanded configuration this eval ran under.
</ResponseField>

<ResponseField name="status" type="string" required>
  Eval lifecycle status; `cancelled` after a successful cancel.
</ResponseField>

<ResponseField name="created_by" type="string" required>
  Subject id (`usr_...` or `key_...`) that created this eval.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Creation timestamp (date-time).
</ResponseField>

<ResponseField name="started_at" type="string">
  When the runner picked the eval up; `null` if it never did.
</ResponseField>

<ResponseField name="completed_at" type="string">
  When the eval finished; `null` while unfinished.
</ResponseField>

<ResponseField name="metrics_report" type="object">
  This is always `null` for a cancelled eval since the report is populated only when an eval
  reaches `completed`.
</ResponseField>

<ResponseField name="output_artifacts" type="array">
  References to the files the run produced. A cancelled eval keeps its partial predictions entry — the
  rows scored so far are still readable.

  <Note>
    A cancelled eval keeps the rows it already scored. Its predictions artifact stays in
    `output_artifacts` with `metadata.status` set to `partial`.
  </Note>
</ResponseField>

<ResponseField name="error" type="string">
  Failure detail; `null` unless the eval failed.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST "$ATAI_API_URL/agents/evals/evl_01jcb0h2m6t4xr9nv3k7pdzs5y/cancel" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```python Python theme={"system"}
  import os
  import requests

  base_url = os.environ["ATAI_API_URL"]
  api_key = os.environ["ATAI_API_KEY"]

  response = requests.post(
      f"{base_url}/agents/evals/evl_01jcb0h2m6t4xr9nv3k7pdzs5y/cancel",
      headers={"Authorization": f"Bearer {api_key}"},
  )

  if response.status_code == 200:
      evaluation = response.json()
      print(f"{evaluation['id']} is now {evaluation['status']}")
  elif response.status_code == 409:
      print("Eval already terminal")
  else:
      print(f"Error: {response.json()['errors']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    `${process.env.ATAI_API_URL}/agents/evals/evl_01jcb0h2m6t4xr9nv3k7pdzs5y/cancel`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
      }
    }
  );

  const body = await response.json();

  if (response.ok) {
    console.log(`${body.id} is now ${body.status}`);
  } else if (response.status === 409) {
    console.error('Eval already terminal');
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Eval cancelled theme={"system"}
  {
    "id": "evl_01jcb0h2m6t4xr9nv3k7pdzs5y",
    "name": "Pump A regression",
    "org_id": "org_01jc8m5r2vq9xt4bn7h3kdzs6w",
    "blueprint_id": "blp_01jc9n7k3xf8mbq2v5t0ary6de",
    "primary": "state.macro_f1",
    "examples": [
      {
        "name": "site-a-morning",
        "ordinal": 1,
        "inputs": [
          {"type": "file", "id": "file_abc123", "format": "csv", "crc32c": "AAAAAA=="}
        ]
      }
    ],
    "rendered_config": {},
    "status": "cancelled",
    "metrics_report": null,
    "output_artifacts": [
      {
        "type": "file",
        "id": "file_jkl012",
        "format": "ndjson",
        "metadata": {"kind": "predictions", "status": "partial", "row_count": 1840}
      }
    ],
    "created_by": "usr_01jc8m4p3rt6vx9qn2h5kdzb7y",
    "created_at": "2026-09-18T11:24:03Z",
    "started_at": "2026-09-18T11:24:09Z",
    "completed_at": null,
    "error": null
  }
  ```

  ```json 404 - Eval not found theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Eval not found.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 409 - Eval already terminal theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Eval already terminal.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.