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

# Events

> Query security and LLM events

## List Events

Retrieve security and audit events for your organization.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  "https://api.prod.turen.io/api/v1/events?limit=50"
```

### Query Parameters

| Parameter   | Type   | Default | Description                                      |
| ----------- | ------ | ------- | ------------------------------------------------ |
| `limit`     | number | 50      | Number of events to return                       |
| `offset`    | number | 0       | Pagination offset                                |
| `type`      | string | all     | Filter by event type: `install`, `audit`         |
| `outcome`   | string | all     | Filter by outcome: `allow`, `review`, `block`    |
| `ecosystem` | string | -       | Filter by ecosystem: `npm`, `pip`, `go`, `cargo` |
| `package`   | string | -       | Filter by package name                           |
| `since`     | string | -       | ISO 8601 timestamp: only events after this time  |
| `until`     | string | -       | ISO 8601 timestamp: only events before this time |

### Response

```json theme={null}
{
  "events": [
    {
      "id": "evt_abc123",
      "client_id": "a1b2c3d4e5f67890",
      "timestamp": "2026-02-17T10:30:00Z",
      "type": "install",
      "outcome": "block",
      "actor": {
        "command": "npm install",
        "args": ["malicious-pkg"],
        "version": "1.2.0"
      },
      "subject": {
        "ecosystem": "npm",
        "package": "malicious-pkg",
        "version": "1.0.0"
      },
      "metadata": {},
      "payload": {
        "reasons": ["Scorecard below minimum threshold (2.1 < 5.0)"]
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1284,
    "has_more": true
  }
}
```

### Response Fields

| Field       | Type   | Description                                           |
| ----------- | ------ | ----------------------------------------------------- |
| `id`        | string | Unique event identifier                               |
| `client_id` | string | Agent that generated the event                        |
| `timestamp` | string | When the event occurred                               |
| `type`      | string | Event type (`install`, `audit`)                       |
| `outcome`   | string | `allow`, `review`, or `block`                         |
| `actor`     | object | What initiated the event (command, args, version)     |
| `subject`   | object | What the event is about (ecosystem, package, version) |
| `metadata`  | object | Additional key-value metadata                         |
| `payload`   | object | Type-specific payload (e.g., reasons for block)       |

## Get Summary Stats

Retrieve aggregate statistics.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/stats/summary
```

### Response

```json theme={null}
{
  "total_events": 1284,
  "outcomes": {
    "allow": 980,
    "review": 215,
    "block": 89
  },
  "ecosystems": {
    "npm": 850,
    "pip": 300,
    "go": 120,
    "cargo": 14
  },
  "period": "30d"
}
```

## Query LLM Events

Retrieve LLM API call events (stored in ClickHouse).

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  "https://api.prod.turen.io/api/v1/events/llm?limit=50"
```

LLM events include provider, model, token counts, latency, and cost data.