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

# Query Events

> List, search, and inspect audit events

## GET /v1/events

List events with optional filters.

### Query parameters

| Parameter     | Type    | Description                                    |
| ------------- | ------- | ---------------------------------------------- |
| `agent_id`    | string  | Filter by agent ID                             |
| `action_type` | string  | Filter by action type                          |
| `since`       | string  | Start time (ISO 8601)                          |
| `until`       | string  | End time (ISO 8601)                            |
| `label.{key}` | string  | Filter by label value (e.g., `label.env=prod`) |
| `limit`       | integer | Max results (default: 100, max: 1000)          |
| `offset`      | integer | Pagination offset                              |

### Example

```bash theme={null}
# List recent events
curl http://localhost:7600/v1/events?limit=20

# Filter by agent
curl http://localhost:7600/v1/events?agent_id=my-agent

# Filter by label
curl "http://localhost:7600/v1/events?label.env=prod&limit=10"
```

### Response

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "my-agent",
    "action_type": "TOOL_CALL",
    "action_name": "search_database",
    "action_status": "success",
    "sequence": 42,
    "hash": "sha256...",
    "timestamp": "2026-02-17T10:30:00Z"
  }
]
```

***

## GET /v1/events/:id

Get a single event by ID.

### Example

```bash theme={null}
curl http://localhost:7600/v1/events/550e8400-e29b-41d4-a716-446655440000
```

Returns `404` if the event is not found.

***

## GET /v1/search

Full-text search across events.

### Query parameters

| Parameter | Type    | Description       |
| --------- | ------- | ----------------- |
| `q`       | string  | Search query      |
| `limit`   | integer | Max results       |
| `offset`  | integer | Pagination offset |

### Example

```bash theme={null}
curl "http://localhost:7600/v1/search?q=search_database&limit=10"
```

***

## GET /v1/agents

List all agents with event counts and chain status.

### Example

```bash theme={null}
curl http://localhost:7600/v1/agents
```

### Response

```json theme={null}
[
  {
    "agent_id": "my-agent",
    "event_count": 150,
    "last_activity": "2026-02-17T10:30:00Z",
    "chain_valid": true
  }
]
```

***

## GET /v1/stats

Aggregate statistics about the audit trail.

### Example

```bash theme={null}
curl http://localhost:7600/v1/stats
```

### Response

```json theme={null}
{
  "total_events": 1500,
  "events_last_24h": 42,
  "active_agents": 5,
  "chain_health": 1.0
}
```