> ## 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.

# Replays

> Re-deliver events through the delivery pipeline

# Replays

The Replay API lets you re-trigger delivery for any stored event. This is useful when your webhook endpoint was temporarily unavailable, when you need to re-process historical data after a configuration change, or when you want to recover from bulk failures.

All replay endpoints are asynchronous — they return `202 Accepted` immediately and process in the background. Monitor progress via the [Events API](./events.md).

All endpoints require a valid JWT session token.

***

## Replay a single event

Re-delivers one specific event by ID.

```text theme={null}
POST /v1/events/replays/single
```

### Request body

| Field           | Type   | Required | Description                                                 |
| --------------- | ------ | -------- | ----------------------------------------------------------- |
| `eventId`       | string | Yes      | The ID of the event to replay                               |
| `replayGroupId` | string | Yes      | A label you provide to group and identify this replay batch |

### Example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/events/replays/single \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "evt_01J8ZXQY5H4KCZP3M2R...",
    "replayGroupId": "manual-retry-2025-01-15"
  }'
```

### Response

```json theme={null}
{
  "status": "initiated"
}
```

### Status codes

| Status            | Meaning                               |
| ----------------- | ------------------------------------- |
| `202 Accepted`    | Replay queued                         |
| `400 Bad Request` | `eventId` is missing                  |
| `403 Forbidden`   | Event does not belong to your account |
| `404 Not Found`   | Event not found                       |

***

## Replay by time range

Re-delivers all events ingested within a specific time window.

```text theme={null}
POST /v1/events/replays/timeline
```

### Request body

| Field           | Type               | Required | Description                           |
| --------------- | ------------------ | -------- | ------------------------------------- |
| `replayGroupId` | string             | Yes      | A label to identify this replay batch |
| `startTime`     | ISO 8601 timestamp | Yes      | Start of the time range (inclusive)   |
| `endTime`       | ISO 8601 timestamp | Yes      | End of the time range (inclusive)     |

### Example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/events/replays/timeline \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "replayGroupId": "backfill-jan-2025",
    "startTime": "2025-01-01T00:00:00Z",
    "endTime": "2025-01-07T23:59:59Z"
  }'
```

### Response

`202 Accepted` with an empty body. Events are processed in batches of 1,000 in the background.

***

## Replay all events

Re-delivers every event in your account history.

```text theme={null}
POST /v1/events/replays/all
```

### Request body

| Field           | Type   | Required | Description                           |
| --------------- | ------ | -------- | ------------------------------------- |
| `replayGroupId` | string | Yes      | A label to identify this replay batch |

### Example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/events/replays/all \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "replayGroupId": "full-history-replay"
  }'
```

### Response

`202 Accepted` with an empty body.

> **Note:** On accounts with large event histories, full replays may take significant time. Consider using the timeline or failed replay options to target a narrower set of events.

***

## Replay failed events

Re-delivers all events currently in the `FAILED` state. This is the most common replay scenario after a period of webhook downtime.

```text theme={null}
POST /v1/events/replays/failed
```

### Request body

| Field           | Type   | Required | Description                           |
| --------------- | ------ | -------- | ------------------------------------- |
| `replayGroupId` | string | Yes      | A label to identify this replay batch |

### Example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/events/replays/failed \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "replayGroupId": "recovery-2025-01-15"
  }'
```

### Response

`202 Accepted` with an empty body.

***

## Choosing a `replayGroupId`

The `replayGroupId` is a string you define to identify a batch of replayed events in your own systems. It is attached to each replayed event in the delivery pipeline. Recommended patterns:

* `"recovery-<date>"` — for post-outage recovery runs
* `"backfill-<feature>"` — for re-processing after a new feature is deployed
* `"manual-<eventId>"` — for one-off single-event retries

The value is not validated beyond being a non-empty string.