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

# Task Runs

> Task-level results within a benchmark run.

Task Runs represent the outcome of a single [Task](/api-reference/resources/tasks) within a [Benchmark Run](/api-reference/resources/runs). Each task run is executed in its own [Playground](/api-reference/resources/playgrounds). When completed, the verification engine produces one [Criterion Run](/api-reference/resources/criterion-runs) per task [Criterion](/api-reference/resources/criteria).

There are two completion paths depending on how the benchmark run was created:

* **Internal (`POST /task-runs/{id}/complete`)**: used by Verial tooling and workers.
* **Public v1 (`POST /v1/task-runs/{id}/complete`)**: used by external agents driving a submission. This is the path an external developer uses; see the [Quick Start](/guides/quickstart).

## Endpoints

| Method | Endpoint                                         | Description                                                  |
| ------ | ------------------------------------------------ | ------------------------------------------------------------ |
| `GET`  | `/task-runs?benchmark_run_id={benchmark_run_id}` | List task runs for a benchmark run                           |
| `GET`  | `/task-runs/{id}`                                | Get task run details (includes `criterion_runs` array)       |
| `POST` | `/task-runs/{id}/complete`                       | Mark a task run complete (internal)                          |
| `POST` | `/task-runs/{id}/cancel`                         | Cancel a task run                                            |
| `POST` | `/v1/task-runs/{id}/start`                       | (Public v1) Mark a task run started                          |
| `POST` | `/v1/task-runs/{id}/complete`                    | (Public v1) Mark complete, runs verification, returns checks |

## Task Run Object

| Field              | Type             | Description                                                           |
| ------------------ | ---------------- | --------------------------------------------------------------------- |
| `id`               | string           | Unique identifier                                                     |
| `benchmark_run_id` | string           | Parent [Benchmark Run](/api-reference/resources/runs)                 |
| `task_id`          | string           | Source [Task](/api-reference/resources/tasks)                         |
| `playground_id`    | string           | [Playground](/api-reference/resources/playgrounds) used for execution |
| `status`           | string           | `active`, `completed`, `cancelled`, `failed`, `timed_out`             |
| `phase`            | string           | `created`, `started`, `completed`                                     |
| `verdict`          | string \| null   | `pass`, `partial`, `fail`. Set on completion                          |
| `score`            | number \| null   | Weighted task score (0 to 1). Set on completion                       |
| `snapshot`         | object \| null   | Frozen copy of the task at execution time                             |
| `started_at`       | datetime \| null | When execution started                                                |
| `completed_at`     | datetime \| null | When execution finished                                               |

The `GET /task-runs/{id}` response includes a `criterion_runs` array. See [Criterion Runs](/api-reference/resources/criterion-runs).

## v1 Completion Response

`POST /v1/task-runs/{id}/complete` runs verification synchronously and returns:

```json theme={null}
{
  "task_run_id": "tr_abc123",
  "phase": "completed",
  "verdict": "partial",
  "score": 0.66,
  "axes": {
    "correctness": { "score": 1.0, "weight": 2 },
    "safety": { "score": 0.0, "weight": 1 }
  },
  "checks": [
    {
      "criterion_id": "crit_01H...",
      "label": "Appointment booked with correct provider",
      "result": "pass",
      "score": 1.0,
      "axis": "correctness",
      "details": "Appointment resource matched; all field assertions passed.",
      "field_results": [
        { "path": "participant.0.actor.display", "expected": "Dr. Rivera", "actual": "Dr. Rivera", "passed": true }
      ]
    }
  ]
}
```

When the benchmark run was created with `scored: true`, the `details` and field-level evidence are omitted from this response to avoid leaking the scoring rubric. You can still fetch full evidence later via `GET /criterion-runs/{id}`.

## SDK Example

```typescript theme={null}
// List task runs for a benchmark run
const taskRuns = await verial.taskRuns.list({ benchmarkRunId: "br_abc123" });

// Get a task run with its criterion runs
const detail = await verial.taskRuns.get({ id: taskRuns.data[0].id });

for (const run of detail.criterionRuns) {
  console.log(`${run.criterionId}: ${run.passed ? "PASS" : "FAIL"} (${run.score})`);
}
```