Skip to content
Kindgi

Query supervisor observations

View as Markdown
GET
/v1/observations
curl --request GET \
  --url 'https://example.com/v1/observations?limit=25&status=succeeded' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated. Any authenticated caller can read observations for their tenant.

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.

status
string
Allowed values: succeeded guardrail-violation guardrail-warning tool-error model-error budget-exceeded aborted other

Filter by observation status.

agentId
string
agentVersion
string

Only the observations of this agent version (with agentId).

supervisorId
string
conversationId
string

Only the observations of turns in this conversation.

since
string format: date-time

Only the observations at or after this time (ISO 8601).

until
string format: date-time

Only the observations at or before this time (ISO 8601).

Responses

Section titled “Responses”

200

Section titled “200”

Page of observations.

Media typeapplication/json
object
data
required
Array<object>
object
id
required
string format: uuid
tenantId
required
string format: uuid
supervisorId
required
string
agentId
required
string
agentVersion
required
string
conversationId
required
string format: uuid
turnNumber
required
integer
status
required
string
Allowed values: succeeded guardrail-violation guardrail-warning tool-error model-error budget-exceeded aborted other
failureCode
string
violations
required
Array<object>
object
key
additional properties
any
failureDetail
object
key
additional properties
any
durationMs
required
integer
costUsd
required
string
provider
object
id
required
string
model
required
string
provenanceRef
object
runId
required
string format: uuid
provenanceId
string format: uuid
observedAt
required
string format: date-time
nextCursor

Opaque cursor for the next page; treat as opaque on the client.

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "status": "succeeded"
    }
  ]
}

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

See also