Skip to content
Kindgi

What a guardrail's checks came to in a project

GET
/v1/guardrails/{guardrailId}/outcomes
curl --request GET \
  --url 'https://example.com/v1/guardrails/example/outcomes?projectId=example&from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z' \
  --header 'Authorization: Bearer <token>'

Counts from the server, over a window: how many of the guardrail’s checks on agent turns in the project passed, were violated (the answer went through: log-only, noop, or an action handed back), blocked (a halt failed the turn) or errored (the check couldn’t run; a halt guardrail’s error fails the turn too, and is counted here). The same counts per agent version, and the window’s latest blocked turns, by run id and time only: a blocked answer stays behind its run’s page. A guardrail whose scope didn’t match a turn wasn’t checked on it. Replays and dry runs aren’t counted. Outcomes go with their run’s retention, so a window can hold fewer than asked; recordedSince says how far back they go. A guardrail no longer registered still has its outcomes. Needs read on the guardrail and on the project.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
guardrailId
required
string

GuardrailId — unique identifier for the guardrail.

Query Parameters

Section titled “Query Parameters”
projectId
required
string
>= 1 characters

The project whose agent turns are counted.

from
required
string format: date-time

Checks at or after this time (ISO 8601).

to
required
string format: date-time

Checks before this time (ISO 8601). At most 90 days after from.

recent
integer
<= 50

How many of the latest blocked turns to name: 0 to 50, 10 by default.

Responses

Section titled “Responses”

200

Section titled “200”

The outcomes.

Media typeapplication/json
object
guardrailId
required
string
from
required
string format: date-time
to
required
string format: date-time
counts
required

How many of a guardrail’s checks came to each outcome.

object
passed
required

The check ran and found nothing.

integer
violated
required

The check found something and the answer went through (log-only, noop, or an action handed back).

integer
blocked
required

The check found something and its halt failed the turn.

integer
errored
required

The check couldn’t run (no such check, a bad configuration, a judge that couldn’t be routed).

integer
byAgentVersion
required

The same counts per agent version, the most checked first, at most 100.

Array<object>

The counts on one agent version’s turns.

object
agentId
required
string
agentVersion
required
string
passed
required

The check ran and found nothing.

integer
violated
required

The check found something and the answer went through (log-only, noop, or an action handed back).

integer
blocked
required

The check found something and its halt failed the turn.

integer
errored
required

The check couldn’t run (no such check, a bad configuration, a judge that couldn’t be routed).

integer
recentBlocked
required

The window’s latest blocked turns, newest first, at most recent.

Array<object>

A turn the guardrail blocked: its run, never its answer.

object
runId
required
string format: uuid
at
required

When the guardrail checked.

string format: date-time
agentId
required
string
agentVersion
required
string
recordedSince

The earliest outcome kept for this guardrail in this project, in any window: nothing before it is counted. Outcomes were first recorded in 0.1.6, and they go with their run’s retention. Absent when none is kept.

string format: date-time
Examplegenerated
{
  "guardrailId": "example",
  "from": "2026-04-15T12:00:00Z",
  "to": "2026-04-15T12:00:00Z",
  "counts": {
    "passed": 1,
    "violated": 1,
    "blocked": 1,
    "errored": 1
  },
  "byAgentVersion": [
    {
      "agentId": "example",
      "agentVersion": "example",
      "passed": 1,
      "violated": 1,
      "blocked": 1,
      "errored": 1
    }
  ],
  "recentBlocked": [
    {
      "runId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "at": "2026-04-15T12:00:00Z",
      "agentId": "example",
      "agentVersion": "example"
    }
  ],
  "recordedSince": "2026-04-15T12:00:00Z"
}

400

Section titled “400”

A missing or malformed projectId, from, to or recent; a window over 90 days.

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

501

Section titled “501”

guardrail-outcomes-not-supported: this deployment doesn’t record guardrail outcomes.

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}