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

# Replay

Replay historical events to a destination with rate limiting and job tracking.

Event replay lets you re-deliver historical events to a destination. Useful for backfilling a new destination, recovering from outages, or testing. Replay jobs are rate-limited and tracked in KV with auto-expiry. You specify a `source_id`, `destination_id`, and time range, and hookstream re-delivers each matching event through the normal delivery pipeline.

## Create Replay Job

POST `/v1/replay`

Create a replay job to re-deliver events from a time range.

**Authentication:** API key or session cookie.

### Body Parameters

Destination to deliver replayed events to.

Filter to events from a specific source.

ISO 8601 start time for the replay window.

ISO 8601 end time for the replay window.

Maximum events per second (max 100).

Maximum events to replay (max 10000).

```bash cURL
curl -X POST https://hookstream.io/v1/replay \
  -H "X-API-Key: $HOOKSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-01T12:00:00Z",
    "rate_limit": 20
  }'
```

```json 201 Created
{
  "job": {
    "id": "rpl_f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7",
    "status": "running",
    "total": 342
  }
}
```

## Get Replay Status

GET `/v1/replay/:id`

Get the status and progress of a replay job.

**Authentication:** API key or session cookie.

```json 200 OK
{
  "job": {
    "id": "rpl_f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7",
    "destination_id": "dst_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "source_id": "src_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-01T12:00:00Z",
    "rate_limit": 20,
    "max_events": 1000,
    "status": "completed",
    "total": 342,
    "processed": 342,
    "succeeded": 340,
    "failed": 2,
    "started_at": "2026-03-01T15:00:00Z",
    "completed_at": "2026-03-01T15:00:18Z"
  }
}
```

### Response Fields

**job.status**

Job status: `running`, `completed`, or `failed`.

**job.processed**

Number of events processed so far.

**job.succeeded**

Number of events successfully delivered.

**job.failed**

Number of events that failed delivery.