Skip to content
Kindgi

List judgments

GET
/v1/judgments
curl --request GET \
  --url 'https://example.com/v1/judgments?limit=25&verdict=yes&scopeKind=tenant' \
  --header 'Authorization: Bearer <token>'

Live judgments (not removed or superseded), newest first, cursor-paginated. Filter by run, agent (and version), flow, verdict, judge class or participant; ?scopeKind + ?scopeId narrow to a project.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “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.

runId
string
>= 1 characters

Only judgments of this run.

agentId
string
>= 1 characters

Only judgments of runs of this agent.

agentVersion
string
>= 1 characters

Only judgments of runs of this agent version. Needs agentId.

flowId
string
>= 1 characters

Only judgments of runs of this flow.

verdict
string
Allowed values: yes no

Only judgments with this verdict.

judgeClassId
string
>= 1 characters

Only judgments recorded under this judge class.

participantId
string
>= 1 characters

Only judgments made for this app end user’s opaque id.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string
Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId
string
>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

Responses

Section titled “Responses”

200

Section titled “200”

Page of judgments.

Media typeapplication/json
object
data
required
Array<object>
object
id
required
string
tenantId
required
string
projectId
required
string
runId
required
string
subject
required

What a judged 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
item
required

The judged item of a run’s output.

object
key
required

The caller’s stable id for the item.

string
>= 1 characters
pointer

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

string
rank

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

integer
verdict
required
string
Allowed values: yes no
reason
string
judgeClassId

The judge class the judgment is recorded under. Absent when unclassified (counts with weight 1).

string
restricted

Present (true) when the judge class was restricted (assertableBy) when the judgment was recorded, so the judge was checked against it. A restriction added or lifted later doesn’t change it.

boolean
assertedBy
required

Who asserted a judgment: the authenticated caller, never a typed name.

object
kind
required
string
Allowed values: user service
id
required

A user id, or for a service token its token or session id.

string
participantId

The app’s opaque id for its end user who judged, when an app judged on their behalf.

string
createdAt
required
string format: date-time
unregisteredAt

Set when the judgment was removed or superseded.

string format: date-time
supersededBy

The judgment that replaced this one.

string
nextCursor

Opaque cursor. Treat as opaque on the client.

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "subject": {
        "kind": "agent"
      },
      "verdict": "yes",
      "restricted": true,
      "assertedBy": {
        "kind": "user"
      }
    }
  ]
}

400

Section titled “400”

Malformed query parameter.

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