Backfills

Backfills let you replay historical blocks for one subscription so you can capture older matching events.

Use this when you created a subscription late, had your endpoint offline, or need a historical range for analysis.

Who Can Use Backfills

Backfill is available when:

your plan includes backfill,
your subscription has Stored Events enabled.

If backfill is unavailable, check your plan/subscription settings in Dashboard.

How To Request A Backfill

Dashboard

Open Dashboard -> Subscriptions -> [subscription] -> Backfill and enter:

from_block
to_block

You can provide one side only to request a single block.

After queueing, Kvasyr shows:

request ID
estimated run window start time
request history with status and cursor progress

API

curl -sS https://app.kvasyr.com/v1/backfill \
  -H "Authorization: Bearer ${KVASYR_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: backfill-sub123-500-1500" \
  -d '{
    "subscription_id": 123,
    "from_block": 500,
    "to_block": 1500
  }'

Use Idempotency-Key so retries do not create duplicate requests.

When It Runs

Backfills run in scheduled windows (not instantly at request time).

What this means for you:

your request enters a queue first (queued),
Kvasyr batches compatible requests to reduce RPC load,
each window has an internal RPC compute budget, so long catch-up runs are intentionally throttled,
the estimate in panel is best-effort and can move if queue load changes.

Throughput Guardrails

Kvasyr applies a per-window estimated RPC budget for backfill work. This keeps historical catch-up from hammering providers during bursts.

default: BACKFILL_MAX_ESTIMATED_CU_PER_TICK=12000
estimate model:
- eth_getLogs ~= 60 CU
- eth_getBlockByNumber ~= 20 CU
- eth_blockNumber ~= 10 CU

If a window hits its budget, remaining work is deferred to the next window instead of continuing unbounded.

Statuses You Will See

queued: waiting for an execution window.
processing: currently scanning your requested range.
paused_credits: stopped because credits ran out; resumes after credits are available.
completed: done.
completed_noop: nothing eligible to scan for that request.
failed: request did not finish and needs review/retry.

Credits And Delivery Behavior

Backfill matches consume credits the same way as live indexing.
Existing matches are deduplicated, so already-matched subscription events are not re-fired as new matches.
Depending on workspace configuration, matched backfill events can also enqueue webhook deliveries in addition to stored-event matching.
For plan-change/reset timing details, see Managing Account and Credits.

Tips For Better Results

Prefer focused ranges over very deep scans when possible.
Split very large history requests into smaller chunks if you need faster checkpoints.
Monitor cursor/status in subscription detail to confirm forward progress.

API Keys and API Managing Account and Credits