> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igrisecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-Time Events

> SSE endpoint for real-time dashboard updates with org-scoped tool call and anomaly events.

# Real-Time Events

Igris provides a Server-Sent Events (SSE) endpoint that streams real-time events to connected clients. The dashboard uses this for live updates, and you can connect your own clients for monitoring and alerting.

## SSE Endpoint

```
GET /api/v1/events
```

**Authentication:** Session cookie or API key required.

**Scoping:** Events are scoped to the authenticated user's active organization. You only receive events for servers belonging to your org.

## Connecting

### Browser (EventSource)

```javascript theme={null}
const eventSource = new EventSource(
  "https://api.igrisecurity.com/api/v1/events",
  { withCredentials: true } // sends session cookie
);

eventSource.addEventListener("tool_call", (event) => {
  const data = JSON.parse(event.data);
  console.log("Tool call:", data.toolName, data.action);
});

eventSource.addEventListener("anomaly", (event) => {
  const data = JSON.parse(event.data);
  console.log("Anomaly detected:", data.type, data.severity);
});
```

### curl

```bash theme={null}
curl -N -H "Authorization: Bearer ig_abc123..." \
  https://api.igrisecurity.com/api/v1/events
```

## Event Types

### `connected`

Emitted immediately after the SSE connection is established, confirming the stream is live.

```json theme={null}
{
  "orgId": "org_abc123"
}
```

### `heartbeat`

Sent every 30 seconds to keep the connection alive.

```json theme={null}
{
  "ts": 1719446400000
}
```

### `tool_call`

Emitted when a tool call is processed by the proxy.

```json theme={null}
{
  "toolName": "read_users",
  "serverId": "db-production",
  "action": "allow"
}
```

### `anomaly`

Emitted when anomaly detection triggers an alert.

```json theme={null}
{
  "type": "rate_spike",
  "toolName": "query_records",
  "serverId": "db-production",
  "severity": "high"
}
```

### `llm_call`

Emitted when a request is processed by the LLM gateway.

### `llm_anomaly`

Emitted when the LLM anomaly detector fires on a gateway request.

<Note>
  Session suspension does not emit an SSE event. When a session is suspended via the kill switch, a `session_suspended` **webhook** is dispatched to any registered webhook endpoints. There is no `session_update` SSE event.
</Note>

## Infrastructure

SSE events are delivered directly to in-process org listeners — the `emitEvent` function looks up registered callbacks for the org and calls them synchronously. Igris also publishes to an Upstash Redis channel (`igris:events`) as a fire-and-forget side-channel; however, the API does not maintain a Redis subscriber loop, so cross-instance fan-out relies on in-process delivery. Clients connected to the same API instance as the event source receive events reliably.