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

# Events Management

> Query and inspect your event history

# Events

The Events API lets you retrieve your event history, inspect individual events, and filter by delivery state. All endpoints require a valid JWT session token.

***

## List events

Returns a paginated list of all events for your account, ordered by ingestion time (newest first).

```text theme={null}
GET /v1/events
```

### Authentication

```text theme={null}
Authorization: Bearer <jwt>
```

### Query parameters

| Parameter | Type    | Default | Maximum | Description               |
| --------- | ------- | ------- | ------- | ------------------------- |
| `page`    | integer | `0`     | —       | Zero-indexed page number  |
| `size`    | integer | `20`    | `1000`  | Number of events per page |

### Example

```bash theme={null}
curl "https://api.eldrstream.com/v1/events?page=0&size=50" \
  -H "Authorization: Bearer <jwt>"
```

### Response

```json theme={null}
{
  "events": [
    {
      "eventId": "evt_01J8ZXQY5H4KCZP3M2R...",
      "tenantId": "a3f8bc1d2e",
      "state": "DELIVERED",
      "ingestionTimestamp": "2025-01-15T10:30:00Z",
      "targetWebhook": "https://example.com/hooks/eldrstream",
      "errorReason": null,
      "originalPayload": {
        "event_type": "order.created",
        "order_id": "ORD-1001"
      }
    }
  ],
  "total": 142
}
```

| Field    | Description                                 |
| -------- | ------------------------------------------- |
| `events` | Array of event objects for the current page |
| `total`  | Total number of events in your account      |

### Event object fields

| Field                | Type           | Description                                  |
| -------------------- | -------------- | -------------------------------------------- |
| `eventId`            | string         | Unique event identifier                      |
| `tenantId`           | string         | Your tenant ID                               |
| `state`              | string         | `DELIVERED` or `FAILED`                      |
| `ingestionTimestamp` | ISO 8601       | When EldrStream received the event           |
| `targetWebhook`      | string         | The webhook URL the event was dispatched to  |
| `errorReason`        | string \| null | Human-readable failure reason, if applicable |
| `originalPayload`    | object \| null | The original payload you sent                |

***

## Get a single event

Returns all event records associated with a specific event ID. If the same event was delivered to multiple webhook endpoints, each delivery appears as a separate entry.

```text theme={null}
GET /v1/events/{id}
```

### Path parameters

| Parameter | Description                                        |
| --------- | -------------------------------------------------- |
| `id`      | The `eventId` returned when the event was ingested |

### Example

```bash theme={null}
curl "https://api.eldrstream.com/v1/events/evt_01J8ZXQY5H4KCZP3M2R..." \
  -H "Authorization: Bearer <jwt>"
```

### Response

```json theme={null}
[
  {
    "eventId": "evt_01J8ZXQY5H4KCZP3M2R...",
    "tenantId": "a3f8bc1d2e",
    "state": "DELIVERED",
    "ingestionTimestamp": "2025-01-15T10:30:00Z",
    "targetWebhook": "https://example.com/hooks/eldrstream",
    "errorReason": null,
    "originalPayload": {
      "event_type": "order.created",
      "order_id": "ORD-1001"
    }
  }
]
```

### Status codes

| Status          | Meaning                               |
| --------------- | ------------------------------------- |
| `200 OK`        | Event found                           |
| `404 Not Found` | No event with that ID in your account |

***

## List events by state

Returns a paginated list of events filtered by delivery state.

```text theme={null}
GET /v1/events/state/{state}
```

### Path parameters

| Parameter | Values                | Description                     |
| --------- | --------------------- | ------------------------------- |
| `state`   | `DELIVERED`, `FAILED` | The delivery state to filter by |

### Query parameters

| Parameter | Type    | Default | Maximum | Description               |
| --------- | ------- | ------- | ------- | ------------------------- |
| `page`    | integer | `0`     | —       | Zero-indexed page number  |
| `size`    | integer | `20`    | `1000`  | Number of events per page |

### Example — list all failed events

```bash theme={null}
curl "https://api.eldrstream.com/v1/events/state/FAILED?page=0&size=100" \
  -H "Authorization: Bearer <jwt>"
```

### Response

```json theme={null}
{
  "events": [
    {
      "eventId": "evt_01J8AABB2C...",
      "tenantId": "a3f8bc1d2e",
      "state": "FAILED",
      "ingestionTimestamp": "2025-01-14T08:12:44Z",
      "targetWebhook": "https://example.com/hooks/eldrstream",
      "errorReason": "HTTP 503 from https://example.com/hooks/eldrstream",
      "originalPayload": { "event_type": "shipment.dispatched" }
    }
  ],
  "total": 3
}
```