Alert Inbox

When a subscription's conditions are met, the system creates a triggered alert event. These events accumulate in your inbox. Use the inbox API to poll for events, filter by criteria, and manage read state.

Listing events

Retrieve triggered alerts with optional filters:

list-inbox.ts

import { Chaos } from '@chaoslabs/ai-sdk';
 
const chaos = new Chaos({ apiKey: process.env.CHAOS_API_KEY! });
 
// List all unread events
const { events, hasMore } = await chaos.alerts.inbox.list({
  readState: 'unread',
});
 
for (const event of events) {
  console.log(`[${event.severity}] ${event.title}`);
  console.log(`  ${event.summary}`);
  console.log(`  Chain: ${event.chain}`);
  console.log(`  Triggered: ${event.triggeredAt}`);
}

Filtering

The list() method accepts an InboxFilters object with several filter options:

Parameter	Type	Description
`readState`	`'all' \| 'unread'`	Filter by read state
`severity`	`AlertSeverity[]`	Filter by severity levels
`category`	`AlertCategory[]`	Filter by alert categories
`includeArchived`	`boolean`	Include archived events (default: `false`)
`limit`	`number`	Max results per page (default: 50)
`offset`	`number`	Pagination offset

filter-examples.ts

// Only critical and warning alerts
const criticals = await chaos.alerts.inbox.list({
  severity: ['critical', 'warning'],
});
 
// Wallet activity alerts, including archived
const walletEvents = await chaos.alerts.inbox.list({
  category: ['wallet-activity'],
  includeArchived: true,
});
 
// Paginate through results
const page1 = await chaos.alerts.inbox.list({ limit: 20, offset: 0 });
const page2 = await chaos.alerts.inbox.list({ limit: 20, offset: 20 });

Unread count

Get a quick count without fetching full events:

unread-count.ts

const { unreadCount } = await chaos.alerts.inbox.unreadCount();
console.log(`${unreadCount} unread alerts`);

Mark as read

Mark individual events as read by their ID:

mark-read.ts

// Mark a single event as read
await chaos.alerts.inbox.markRead('ta-60a5a3feae3b');
 
// Mark all events for a subscription as read
const { markedCount } = await chaos.alerts.subscriptions.markRead('ua-abc123');
console.log(`Marked ${markedCount} events as read`);

Archiving events

Archive events to remove them from the default inbox view:

archive.ts

await chaos.alerts.inbox.archive('ta-60a5a3feae3b');
 
// Archived events can still be retrieved with includeArchived
const { events } = await chaos.alerts.inbox.list({ includeArchived: true });

Event evidence

Each triggered alert includes evidence data that explains why it fired:

evidence.ts

const { events } = await chaos.alerts.inbox.list();
 
for (const event of events) {
  // Data points — key metrics that triggered the alert
  for (const dp of event.evidence.dataPoints) {
    console.log(`  ${dp.label}: ${dp.value}${dp.unit ? ` ${dp.unit}` : ''}`);
  }
 
  // Chart data — time series for visualization
  if (event.evidence.chartData) {
    const { timestamps, values, threshold_line } = event.evidence.chartData;
    console.log(`  Chart: ${values.length} data points`);
    if (threshold_line) console.log(`  Threshold: ${threshold_line}`);
  }
 
  // Source links — references for further investigation
  if (event.evidence.sourceLinks) {
    for (const link of event.evidence.sourceLinks) {
      console.log(`  ${link.label}: ${link.url}`);
    }
  }
 
  // Transaction context — on-chain transaction details (if applicable)
  if (event.transactionContext) {
    const tx = event.transactionContext;
    console.log(`  Tx: ${tx.transactionHash}`);
    console.log(`  Block: ${tx.blockNumber} at ${tx.blockTimestamp}`);
    console.log(`  From: ${tx.fromAddress} To: ${tx.toAddress}`);
  }
}

Subscription-level events

Get events for a specific subscription:

subscription-events.ts

const { events, total } = await chaos.alerts.subscriptions.getEvents('ua-abc123');
console.log(`${total} total triggers for this subscription`);

Polling pattern

For applications that poll the inbox on an interval:

polling-pattern.ts

async function pollInbox(chaos: InstanceType<typeof Chaos>) {
  const { events } = await chaos.alerts.inbox.list({ readState: 'unread' });
 
  for (const event of events) {
    await processAlert(event);
    await chaos.alerts.inbox.markRead(event.id);
  }
}
 
// Poll every 30 seconds
setInterval(() => pollInbox(chaos), 30_000);

Next steps

Real-time Alerts — Stream alerts via WebSocket
Webhook Delivery — Push alerts to your server
Alerts API Reference — Full type definitions

Was this helpful?

Alert Inbox

On this page