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

GET

/v1/runs/failures

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>'

• Same-origin — path relative to the deployment root.

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

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.

Media typeapplication/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

{
  "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.

Media typeapplication/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

Example^generated

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

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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

Example^generated

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

501

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

Media typeapplication/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

Example^generated

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