Exceptions

Get an exception item

Returns a single exception item with its full detail.

get/v1/projects/{project_id}/exceptions/{exception_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/exceptions/{exception_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

exception_idstring required
Example:exc_V1StGXR8Z5jdHi6B

Exception item ID

Response

Exception item

idstring
project_idstring
status'open' | 'acknowledged' | 'resolved'
severity'info' | 'warning' | 'critical'
kind'run_failed' | 'guardrail_tripwire' | 'approval_expired' | 'quota_unpriced' | 'event_trigger_loop' | 'chain_limit' | 'manual'

How the exception was filed

titlestring

Human-readable one-line summary

detailobject nullable

Structured context (tool, args digest, error message, guardrail version)

occurrence_countinteger

How many times this exact failure has been observed while open

last_seen_atstring date-time

Timestamp of the most recent occurrence

orchestration_run_idstring nullable

Originating orchestration run

node_idstring nullable

Originating node id within the run's graph

agent_idstring nullable

Associated agent

guardrail_versionstring nullable

<guardrailId>@<version> for a guardrail_tripwire exception

acknowledged_by_principal_type'user' | 'api_key' | 'agent' | 'automation' | 'approval' | 'system'

What kind of principal acted. user and api_key are authenticated callers, and the id is the user's (user_…) or the key's own (key_…), so a record names which key acted rather than its owner. agent is an agent writing under its own identity (agent_…). automation is the task engine acting on a dispatch outcome and approval an approval resolution; neither carries an id. system is the platform itself, with an id naming the mechanism (retention_sweep, zero_retention).

acknowledged_by_principal_idstring nullable

Public id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted.

resolved_by_principal_type'user' | 'api_key' | 'agent' | 'automation' | 'approval' | 'system'

What kind of principal acted. user and api_key are authenticated callers, and the id is the user's (user_…) or the key's own (key_…), so a record names which key acted rather than its owner. agent is an agent writing under its own identity (agent_…). automation is the task engine acting on a dispatch outcome and approval an approval resolution; neither carries an id. system is the platform itself, with an id naming the mechanism (retention_sweep, zero_retention).

resolved_by_principal_idstring nullable

Public id of that principal: the user (user_…), or for API key auth the key itself (key_…), so the record names which key acted.

resolution_notestring nullable

Optional note recorded at resolution

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "exc_V1StGXR8Z5jdHi6B",
  "acknowledged_by_principal_type": "user",
  "acknowledged_by_principal_id": "user_V1StGXR8Z5jdHi6B",
  "resolved_by_principal_type": "user",
  "resolved_by_principal_id": "user_V1StGXR8Z5jdHi6B"
}

Changes

No recorded changes to this operation across all 1 revision of this API.