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_id string required

Destination to deliver replayed events to.

source_id string

Filter to events from a specific source.

from string required

ISO 8601 start time for the replay window.

to string required

ISO 8601 end time for the replay window.

rate_limit number default: 10

Maximum events per second (max 100).

max_events number default: 1000

Maximum events to replay (max 10000).

bash
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
{
  "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
{
  "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 string

Job status: running, completed, or failed.

job.processed number

Number of events processed so far.

job.succeeded number

Number of events successfully delivered.

job.failed number

Number of events that failed delivery.

Was this page helpful?

Previous Topics

Next Test Sessions