# A project's failed runs, grouped by cause and version

GET

/v1/runs/failures

```sh
curl --request GET \
  --url 'https://example.com/v1/runs/failures?projectId=example&from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z' \
  --header 'Authorization: Bearer <token>'
```

Counts from the server, never from a page: per group, how many runs failed, when the first and the latest failed in the window, and the latest run. People’s decisions (`hitl-*`: an approval rejected, cancelled or timed out) come apart as `outcomes`, never as failures. Runs that failed before their cause was recorded come apart as `unrecorded`, by subject and version only. Replays, eval runs’ runs and dry runs aren’t counted; a child run counts under its own agent or flow. Failed runs go with their retention, so a window can hold fewer than happened. Needs `read` on the project.

## Authorizations

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

## Parameters

### Query Parameters

**projectId**

required

string

\>= 1 characters

The project whose runs are counted.

**from**

required

string format: date-time

Runs that failed at or after this time (ISO 8601).

**to**

required

string format: date-time

Runs that failed before this time (ISO 8601). At most 90 days after `from`.

**agentId**

string

\>= 1 characters

Only this agent’s turns. Not with `flowId`.

**flowId**

string

\>= 1 characters

Only this flow’s runs. Not with `agentId`.

**groupBy**

string

What failures are grouped by: `code`, `version`, or `code,version` (the default).

**limit**

integer

\>= 1 <= 200

The most groups in each list, the most failures first: 1 to 200, 50 by default.

## Responses

### 200

The groups.

application/json

object

**from**

required

string format: date-time

**to**

required

string format: date-time

**groups**

required

The failures, the most first.

Array\<object>

One group of failed runs: the same cause, subject and version.

object

**code**

The failure’s code (`Run.failure.code`). Absent when not grouped by code, and in `unrecorded`.

string

**reason**

The failure’s reason (`Run.failure.reason`), when it gives one: a `hitl-*` outcome’s, e.g. `timeout`.

string

**subject**

required

Whose runs a failure group counts: an agent’s turns, or a flow’s runs.

object

**kind**

required

string

Allowed values: agent flow

**id**

required

string

**version**

The agent’s or flow’s version. Absent when not grouped by version, or not recorded for the run.

string

**count**

required

integer

\>= 1

**firstSeen**

required

When the first of them failed, in the window.

string format: date-time

**lastSeen**

required

When the latest of them failed, in the window.

string format: date-time

**exampleRunId**

required

The group’s most recent run.

string format: uuid

**outcomes**

required

People’s decisions, never errors: `hitl-*` codes (an approval rejected, cancelled or timed out), the most first.

Array\<object>

One group of failed runs: the same cause, subject and version.

object

**code**

The failure’s code (`Run.failure.code`). Absent when not grouped by code, and in `unrecorded`.

string

**reason**

The failure’s reason (`Run.failure.reason`), when it gives one: a `hitl-*` outcome’s, e.g. `timeout`.

string

**subject**

required

Whose runs a failure group counts: an agent’s turns, or a flow’s runs.

object

**kind**

required

string

Allowed values: agent flow

**id**

required

string

**version**

The agent’s or flow’s version. Absent when not grouped by version, or not recorded for the run.

string

**count**

required

integer

\>= 1

**firstSeen**

required

When the first of them failed, in the window.

string format: date-time

**lastSeen**

required

When the latest of them failed, in the window.

string format: date-time

**exampleRunId**

required

The group’s most recent run.

string format: uuid

**unrecorded**

required

Runs that failed before their cause was recorded (a runtime from before this): by subject and version only, never by code.

Array\<object>

One group of failed runs: the same cause, subject and version.

object

**code**

The failure’s code (`Run.failure.code`). Absent when not grouped by code, and in `unrecorded`.

string

**reason**

The failure’s reason (`Run.failure.reason`), when it gives one: a `hitl-*` outcome’s, e.g. `timeout`.

string

**subject**

required

Whose runs a failure group counts: an agent’s turns, or a flow’s runs.

object

**kind**

required

string

Allowed values: agent flow

**id**

required

string

**version**

The agent’s or flow’s version. Absent when not grouped by version, or not recorded for the run.

string

**count**

required

integer

\>= 1

**firstSeen**

required

When the first of them failed, in the window.

string format: date-time

**lastSeen**

required

When the latest of them failed, in the window.

string format: date-time

**exampleRunId**

required

The group’s most recent run.

string format: uuid

**total**

required

Every failed run in the window, across the three lists.

integer

##### Example

```json
{
  "groups": [
    {
      "subject": {
        "kind": "agent"
      }
    }
  ],
  "outcomes": [
    {
      "subject": {
        "kind": "agent"
      }
    }
  ],
  "unrecorded": [
    {
      "subject": {
        "kind": "agent"
      }
    }
  ]
}
```

### 400

A missing or malformed `projectId`, `from`, `to`, `groupBy` or `limit`; a window over 90 days; both `agentId` and `flowId`.

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"
  }
}
```

### 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"
  }
}
```

### 501

`run-failures-not-supported`: this deployment cannot group failed runs by cause.

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

- [Operate a self-hosted runtime](https://docs.kindgi.com/v0.1.9/deploy/self-hosted/operate.md)
- [See why runs failed](https://docs.kindgi.com/v0.1.9/guides/runs/see-why-runs-failed.md)
- [Error code `run-failures-not-supported`](https://docs.kindgi.com/v0.1.9/reference/errors.md#run-failures-not-supported)
- [Every error code](https://docs.kindgi.com/v0.1.9/reference/errors.md)