# Backfills

A new signal is answered from each object's next analysis. To answer it for
the objects you already have, run a **backfill**: a re-analysis of every
object that has no answer for the signal, for that signal only.

## Estimate first

Each analysis is billed, so check what a backfill would cost:

```bash
curl "$API/v1/signals/wants_refund/backfill?api_key=$ANALYZE_API_KEY" -H "Authorization: Bearer $(sign)"
```

```json
{
  "estimate": { "objects": 12840, "estimated_cost_micros": 25680000 },
  "backfill": null
}
```

`estimated_cost_micros` is in micro-dollars (here $25.68), an upper bound based
on your recent average cost per analysis. `backfill` is the progress of the
last backfill, or `null`.

## Start it

```bash
curl -X POST "$API/v1/signals/wants_refund/backfill?api_key=$ANALYZE_API_KEY" -H "Authorization: Bearer $(sign)"
```

```json
{ "signal_key": "wants_refund", "status": "running", "total": 12840, "completed": 0, "pending": 12840, "started_at": "2026-09-27T10:00:00Z" }
```

Backfill jobs run at **bulk priority**: live traffic is always served first,
so a large backfill never delays the analysis of new events. Poll the `GET`
above to follow `completed` and `pending`; `status` becomes `done` when nothing
is left.

A disabled signal can't be backfilled (`409`). Enable it first.

## Automatic backfills

Set `auto_backfill_signals` to backfill every new signal as soon as it is
created. It is off by default because of the cost.

```bash
curl -X PATCH "$API/v1/settings?api_key=$ANALYZE_API_KEY" \
  -H "Authorization: Bearer $(sign)" -H 'Content-Type: application/json' \
  -d '{"auto_backfill_signals":true}'
```

With it on, the signal returned by `PUT /v1/signals/{key}` includes the
started `backfill`.