Anomaly Detection

Detect, list, and acknowledge anomalous agent behavior patterns.

Overview

The anomalies sub-client provides automated anomaly detection for agent activity. It identifies unusual patterns such as rate spikes, high failure rates, new principals, and off-hours activity.

const result = await grantex.anomalies.detect();
console.log(result.total);     // 3
for (const anomaly of result.anomalies) {
  console.log(`[${anomaly.severity}] ${anomaly.type}: ${anomaly.description}`);
}

---

anomalies.detect()

Run anomaly detection across all agents and return any newly detected anomalies.

const result = await grantex.anomalies.detect();

console.log(result.detectedAt);  // '2026-02-28T12:00:00Z'
console.log(result.total);       // 2
for (const anomaly of result.anomalies) {
  console.log(anomaly.id);          // 'anom_01HXYZ...'
  console.log(anomaly.type);        // 'rate_spike'
  console.log(anomaly.severity);    // 'high'
  console.log(anomaly.description); // 'Agent ag_01HXYZ... had 500% more requests than usual'
  console.log(anomaly.agentId);     // 'ag_01HXYZ...'
  console.log(anomaly.metadata);    // { normalRate: 10, currentRate: 60 }
}

Response: DetectAnomaliesResponse

detectedAt · string

ISO 8601 timestamp when detection was run.

total · number

Number of anomalies detected.

anomalies · Anomaly[]

Array of detected anomalies.

Anomaly types

Type	Description
rate_spike	Abnormally high request volume for an agent
high_failure_rate	Unusually high proportion of failed actions
new_principal	An agent is acting on behalf of a previously unseen user
off_hours_activity	Agent activity outside normal business hours

Anomaly severity levels

Severity	Description
low	Informational, may not require action
medium	Worth investigating
high	Likely requires immediate attention

---

anomalies.list()

List stored anomalies. Optionally filter to only unacknowledged anomalies.

// List all anomalies
const all = await grantex.anomalies.list();

// List only unacknowledged anomalies
const open = await grantex.anomalies.list({ unacknowledged: true });

console.log(open.total); // 5
for (const anomaly of open.anomalies) {
  console.log(`${anomaly.type} (${anomaly.severity}) - ${anomaly.detectedAt}`);
}

Parameters

unacknowledged · boolean

When true, only return anomalies that have not been acknowledged.

Response: ListAnomaliesResponse

anomalies · Anomaly[]

Array of anomaly objects.

total · number

Total number of anomalies matching the filter.

---

anomalies.acknowledge()

Acknowledge an anomaly by ID. This marks it as reviewed so it no longer appears in the unacknowledged list.

const anomaly = await grantex.anomalies.acknowledge('anom_01HXYZ...');

console.log(anomaly.acknowledgedAt); // '2026-02-28T12:30:00Z'

Parameters

anomalyId · string · required

The anomaly ID to acknowledge.

Response: Anomaly

Returns the updated anomaly object with the acknowledgedAt timestamp set.

Anomaly object

id · string

Unique anomaly identifier.

type · AnomalyType

The anomaly type: 'rate_spike', 'high_failure_rate', 'new_principal', or 'off_hours_activity'.

severity · AnomalySeverity

Severity level: 'low', 'medium', or 'high'.

agentId · string | null

The agent associated with the anomaly, if applicable.

principalId · string | null

The user associated with the anomaly, if applicable.

description · string

Human-readable description of the anomaly.

metadata · Record<string, unknown>

Additional context about the anomaly (e.g. request rates, thresholds).

detectedAt · string

ISO 8601 timestamp when the anomaly was detected.

acknowledgedAt · string | null

ISO 8601 timestamp when the anomaly was acknowledged, or null.