# List the cases of a corrections test set version

GET

/v1/test-sets/{testSetId}/versions/{version}/cases

```sh
curl --request GET \
  --url 'https://example.com/v1/test-sets/example/versions/example/cases?limit=25' \
  --header 'Authorization: Bearer <token>'
```

Cursor-paginated, in the order the cases were stored (newest corrected run first).

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**testSetId**

required

string

\>= 1 characters

TestSetId — stable string chosen by the caller (e.g. `acme.drafting-accuracy`).

**version**

required

string

/^\d+\\.\d+\\.\d+$/

Semver version string of the test set (e.g. `1.2.0`).

### Query Parameters

**limit**

integer

default: 25 >= 1 <= 100

1..100. Default 25.

**cursor**

string

Where the previous page ended: its `nextCursor`, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise `400 bad-input`, and the list starts again without it. Absent → first page.

## Responses

### 200

Page of cases.

application/json

object

**data**

required

Array\<object>

One case of a `corrections` test set: a copy of a corrected run with its items’ corrections summed up.

object

**caseId**

required

The case’s id. A frozen case of an agent’s test set has its correction’s id, or a `case-` id when it was added by hand. A `corrections` test set built before 0.4.0 used the corrected run’s id.

string

**runId**

The run the case was copied from. Absent from older servers: there a case of a `corrections` test set built before 0.4.0 has the run’s id as its `caseId`.

string

**subject**

required

What a corrected run ran: an agent at a version, or a flow at a version.

object

**kind**

required

string

Allowed values: agent flow

**id**

required

string

**version**

required

string

**input**

required

**context**

What a corrected run needs besides its input to be replayed, captured when it was first corrected. For an agent turn: the conversation before it, what its retrievals returned, and the decision at its session approval gate. For a flow run: its tool calls with their results. For both: the env values its tools were sent.

object

**history**

The conversation’s messages before the turn, oldest first (at most the last 200).

Array

**historyTruncated**

Whether older messages were left out of `history`.

boolean

**retrieved**

What the turn’s retrievals returned.

**recalled**

Messages of earlier conversations the turn recalled (intents over conversations), as quoted to the model.

**sessionApproval**

The reviewer’s decision at the turn’s session approval gate, when the turn waited on one. A replay of the turn follows it.

object

**approved**

required

boolean

**rationale**

The reviewer’s reason for a rejection.

string

**flow**

For a flow run: what it did, kept at its first correction so it can be replayed. Every tool call it made with its result (at its tool nodes, in its agent steps’ turns and in its sub-flows), at most 500, and its agent steps.

object

**calls**

required

Array\<object>

object

**runId**

required

The run that made it: the flow run, a sub-flow’s, or an agent step’s turn.

string

**nodeId**

The tool node that made it, or the agent step whose turn did.

string

**scope**

The loop iteration, in a loop body.

string

**toolId**

required

string

**arguments**

**result**

**fromEvent**

An agent step’s turn kept the result as outside data: another system’s answer to a paused call, or a result its tool says is outside data. A replay hands it to the model as data, as the turn did. Absent for a tool node’s call, and for a run corrected before the mark was kept.

boolean

**steps**

required

Array\<object>

object

**runId**

required

string

**nodeId**

string

**scope**

string

**agentId**

required

string

**agentVersion**

required

string

**retrieved**

What the step’s turn retrieved.

**recalled**

Messages of earlier conversations the step’s turn recalled.

**truncated**

More calls were made than were kept.

boolean

**toolEnv**

The env values each tool’s calls were sent (`needsSpec.env`), by tool id: its first call’s, as the run recorded them. A replay sends them to a read-only tool it runs live, so the tool reads the config the run saw, not today’s. Absent for a run from before env was recorded.

object

**_key_**

additional properties

object

**_key_**

additional properties

string

**replayOf**

When the corrected run is a comparison’s replay: the run it re-ran, stamped at its first correction. A test set built from corrections leaves replays out.

string

**output**

required

**segments**

The segment path its run was started with, coarse to fine (empty: none). Set on a frozen case of an agent’s test set when its run’s copy has it.

Array\<object>

object

**key**

required

Lowercase, like an identifier: `company`, `contact-role`.

string

/^\[a-z]\[a-z0-9\_-]{0,63}$/

**value**

required

string

\>= 1 characters <= 256 characters

**items**

required

Array\<object>

The corrections of one item of a case’s output, summed up.

object

**key**

required

string

**pointer**

string

**rank**

integer

**yes**

required

How many corrections said yes.

integer

**no**

required

How many corrections said no.

integer

**yesWeight**

required

The weight behind “yes” (an unclassified correction counts 1).

number

**totalWeight**

required

The weight behind all corrections of the item.

number

**expert**

The same weights, counting only corrections recorded while their group was restricted (`Correction.expert`), for a comparison weighted `experts-only`. Absent from a test set built before restrictions.

object

**yesWeight**

required

number

**totalWeight**

required

number

**correctionIds**

The corrections behind these two. Absent from a test set built before correction ids.

Array\<string>

**correctionIds**

The corrections summed into the item, by id: what a comparison on this case counts. Absent from a test set built before correction ids.

Array\<string>

**reasons**

required

The reasons given, newest first.

Array\<object>

object

**verdict**

required

string

Allowed values: yes no

**reason**

required

string

**correctorGroupId**

The correction’s group, when it had one.

string

**expert**

Set when the correction was recorded while its group was restricted (`Correction.expert`).

boolean

**corrections**

Experts’ expected decisions carried onto this case from its corrections, each graded on the replay. Empty or absent when none. `experts-only` keeps only the entries whose correction was restricted.

Array\<object>

object

**correctionId**

required

The correction they were recorded on.

string

**correctorGroupId**

The correction’s group, when it had one.

string

**expert**

Set when the correction was recorded while its group was restricted (`Correction.expert`).

boolean

**calls**

required

The calls the agent should have made.

Array\<object>

<= 50 items

object

**tool**

required

string

\>= 1 characters <= 200 characters

**args**

required

The partial set of top-level argument fields to compare, by value. Fields left out are not compared; an empty object asks only that the tool was called. At most 4000 characters in canonical JSON.

object

<= 100 properties

**notCalled**

required

Tools that should not have been called at all.

Array\<string>

<= 50 items

**expect**

What the case expects of a run, as the agent’s test set lists it. Set on a frozen case of an agent’s test set, from its own correction or hand case, which also fill `items` and `corrections`. A grader reads it when it’s present, and `items` and `corrections` otherwise.

object

**decisions**

`right`: it calls the same tools the corrected run called, by name, in any order (args aren’t compared). `wrong`: it calls every `shouldCall` tool (with its `args` where given) and none of `mustNotCall`, checked exactly, without a model.

object

**verdict**

required

string

Allowed values: right wrong

**shouldCall**

Array\<object>

object

**tool**

required

string

\>= 1 characters <= 200 characters

**args**

required

The partial set of top-level argument fields to compare, by value. Fields left out are not compared; an empty object asks only that the tool was called. At most 4000 characters in canonical JSON.

object

<= 100 properties

**mustNotCall**

Array\<string>

**answer**

A judging model checks it. `right`: it says what the corrected run’s answer said. `wrong`: it does what `shouldSay` or `why` asks.

object

**verdict**

required

string

Allowed values: right wrong

**shouldSay**

string

**why**

string

**items**

A ranked answer’s items, scored as `weightedPrecisionAtK`.

Array\<object>

object

**key**

required

The caller’s stable id for the item, such as a matched case’s id, never the item’s own text.

string

\>= 1 characters

**pointer**

Where the item is in the run’s output, as a JSON Pointer (RFC 6901), e.g. `/matches/2`.

string

**rank**

The item’s position in the ranked list (0 = first).

integer

**verdict**

required

string

Allowed values: right wrong

**expert**

Present (true) on a frozen case whose test case is an expert’s: a test run weighted `experts-only` grades its `expect`, and drops the `expect` of every other case. Absent from older servers.

boolean

**erased**

An erasure cleared this case (a person’s words were erased): `input` and `output` are null, `items` empty, `corrections`, `expect` and `segments` gone, and test runs leave it out (counted as `erased`).

boolean

**nextCursor**

Opaque cursor. Treat as opaque on the client.

string

**hasMore**

required

boolean

##### Example

```json
{
  "data": [
    {
      "subject": {
        "kind": "agent"
      },
      "context": {
        "flow": {
          "calls": [
            {
              "fromEvent": true
            }
          ]
        }
      },
      "items": [
        {
          "reasons": [
            {
              "verdict": "yes",
              "expert": true
            }
          ]
        }
      ],
      "corrections": [
        {
          "expert": true
        }
      ],
      "expect": {
        "decisions": {
          "verdict": "right"
        },
        "answer": {
          "verdict": "right"
        },
        "items": [
          {
            "verdict": "right"
          }
        ]
      },
      "expert": true,
      "erased": true
    }
  ]
}
```

### 401

Missing / malformed / expired / revoked bearer token.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

No test set with that id.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 503

The database was too busy to answer in time (`database-busy`); `Retry-After` (whole seconds) says when to try again.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`GET /v1/test-sets/{testSetId}`: Fetch a test set (latest version)](https://docs.kindgi.com/reference/api/operations/testsetsget.md)
- [`GET /v1/test-sets/{testSetId}/versions`: List versions of a test set](https://docs.kindgi.com/reference/api/operations/testsetsversionslist.md)
- [`GET /v1/test-sets/{testSetId}/versions/{version}`: Fetch a specific test set version](https://docs.kindgi.com/reference/api/operations/testsetsversionsget.md)
- [`POST /v1/test-sets/{testSetId}/versions/{version}/unregister`: Unregister a test set version](https://docs.kindgi.com/reference/api/operations/testsetsversionsunregister.md)
- [An agent's test set](https://docs.kindgi.com/guides/improve/build-a-test-set.md)
- [Error code `database-busy`](https://docs.kindgi.com/reference/errors.md#database-busy)
- [Every error code](https://docs.kindgi.com/reference/errors.md)