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

# Backfills

> Process a chosen range of historical schedule windows. Preview the windows before starting, decide which existing runs make a window eligible, and limit concurrent execution.

How-to guideApplies to: Unified engine deployments

Process a chosen range of historical schedule windows. Preview the windows before starting, decide which existing runs make a window eligible, and limit concurrent execution.

## Before you start

Use a saved batch workload with a cron or interval schedule and no incremental cursor. For window-filtered SQL, enable data windows and bind their start and end explicitly.

Start with the inline workload in [Data windows](https://docs.e6data.com/transformation/workloads/data-windows.md). Save a daily midnight UTC cron schedule, then pause the workload while preparing the historical range. Resume it before creating the backfill. Saving or resuming a live schedule can also create normal scheduled work.

Backfills use the normal run execution path. They keep their own window list and do not move the live schedule cursor through the historical range.

## 1. Preview two complete days

Open the workload's **Backfills** tab and select **Create backfill**. Set the start and end to the local equivalents of January 1 and January 3, 2026, at 00:00 UTC. The fields show your browser's time zone. In Asia/Kolkata, enter 05:30 on both dates.

Choose **Missing only**, one concurrent run, and leave **Newest windows first** off. Select **Preview windows** to inspect the included and excluded counts.

The HTTP preview below exposes the complete window list and exclusion reasons. Use it when you need to inspect each decision before creation.

Use a fresh submission ID and the current saved workload revision:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/workloads/{workload_id}/backfills/preview
Content-Type: application/json
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "submission_id": "44444444-4444-4444-8444-444444444444",
  "expected_revision": 2,
  "from_unix_millis": 1767225600000,
  "to_unix_millis": 1767398400000,
  "parameters": {},
  "reprocess": "missing",
  "max_active_runs": 1,
  "run_backwards": false
}
```

Replace revision 2 with the actual revision. The range is January 1 through January 3, 2026, exclusive. Expect two daily windows. Preview lists each window and whether it is pending or excluded, with its reason. It does not create execution work.

Boundaries must align with complete schedule windows. Partial periods are rejected. A preview can contain at most 4,096 windows, so split larger ranges.

## 2. Choose reprocessing behavior

| Value | Windows considered for processing |
| - | - |
| `missing` | Windows with no recorded matching occurrence. |
| `failed` | Missing windows and eligible windows whose latest matching run failed or was cancelled. |
| `all` | Missing windows and eligible completed windows, including successful ones. |

Active or uncertain runs are excluded. Unavailable history is not evidence that replay is safe. Inspect preview reasons before changing the policy.

`max_active_runs` is 1–64, with a default of 1. It is an upper bound for this backfill; overlap rules and available capacity can reduce actual concurrency. `run_backwards` reverses submission order, but overlapping execution can still finish in another order.

## 3. Create and inspect

Select **Start backfill** after reviewing the range and policy. Through HTTP, POST the reviewed request to `/api/v1/workloads/{workload_id}/backfills`. Creation records the definition, revision, schedule, effective options, parameters, and planned windows for this backfill.

Use the same submission ID and identical request to recover a lost create response. A genuinely new backfill needs a new submission ID. Preview again if the workload changes before acceptance.

For the inline example, January 1 should produce two orders and sales of 50; January 2 should produce two orders and sales of 55. Follow the created run IDs, recorded windows, task states, and any destination commits.

## 4. Pause, resume, or cancel

In the Backfills tab, open a record to inspect its windows and follow **View run** links. Use **Pause**, **Resume**, or **Cancel** on an active backfill.

Read progress with GET `/api/v1/workloads/{workload_id}/backfills/{backfill_id}`. Change the backfill with POST to the same route:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "action": "pause" }
```

Execution actions are `pause`, `resume`, and `cancel`. The `retry_notifications` action retries exhausted backfill event deliveries with their original event IDs. It does not rerun windows or change a terminal backfill outcome. Pausing holds future submissions. Cancelling stops further planned submissions and requests cancellation of submitted runs. Follow those runs until their final state is confirmed. Neither action rolls back committed writes.

Pausing a backfill is separate from pausing the workload's live schedule. Check both when stopping all future work.

## Repeat safely

A backfill is not one transaction. Some windows can succeed while others fail. Read per-window status and commit evidence, then preview the required follow-up range. For task-level recovery within a completed run, use [Selective reruns](https://docs.e6data.com/transformation/workloads/reruns.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.