---
title: "Request backfill"
method: POST
path: "/v0/admin/backfills"
tags: ["Admin"]
---

# Request backfill

`POST /v0/admin/backfills`

## Request

- Base URL: `https://docs.quivr.thevibecompany.co` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.quivr.thevibecompany.co/v0/admin/backfills`
- Auth: HTTP bearer

Reprocess a Corpus's past Versions with a selected active ingestion plugin, to fill vector spaces of the generation the Corpus is routed to, typically a new evaluation space. The scope is the Corpus and, optionally, a window on when Quivr accepted its Versions. Only Versions segmented by the selected plugin whose segments all hold a vector in the served space and miss one in a target space are processed; live enrichment fills the target spaces for newer Versions once the backfill has started. A dry run is required. dry_run true answers 200 with the estimate and records it under the idempotency key. The same body with dry_run false then accepts the backfill as a queued Operation (202, Location). Without a dry run recorded under that key and scope, the answer is 409 dry_run_required. An estimated cost above the deployment's backfill.max_cost_without_confirmation needs confirm_cost true, otherwise 409 cost_confirmation_required. The same key with another scope is 409 idempotency_conflict, and an accepted key replays its Operation. A Corpus whose previous backfill has not finished is 409 backfill_in_progress. The backfill runs on its own task queue at the deployment's backfill.rate, pinned to the Pipeline Plan active when it starts. It can be paused, resumed and canceled, and resumes from its checkpoint after a restart. It never creates Record Versions or content events. Versions whose projected segments the plugin would cut differently are skipped and counted (segmentation_differs), and a rebuild re-segments them. Requires plugins:admin, on a key of the Corpus's Organization that grants the Corpus.

## Request body

- BackfillRequest
  - `idempotency_key` string, required
  - `corpus_id` string, required
  - `accepted_after` string, date-time: Only Versions Quivr accepted at or after this time; absent, from the first.
  - `accepted_before` string, date-time: Only Versions Quivr accepted before this time; absent, up to now.
  - `registration_id` string: The ingestion plugin registration to run; absent, the active plan's default. Any ingestion member of the active plan is accepted; a registration outside it is 409 registration_not_active.
  - `spaces` string[]: The vector spaces to fill, which the plugin declares and the deployment serves or evaluates; absent, the deployment's evaluation spaces the plugin owns.
  - `dry_run` boolean, required: true reports the estimate and records it; false starts the backfill a dry run with the same key and scope preceded.
  - `confirm_cost` boolean: Accept an estimated cost above the deployment's backfill.max_cost_without_confirmation.

## Response `200`

The dry run's estimate, recorded under the key.

- BackfillEstimate
  - `registration_id` string, required
  - `spaces` string[], required
  - `versions` integer, required: Versions in scope that miss a vector in a target space.
  - `segments` integer, required: Their segments, which the plugin embeds.
  - `input_tokens` integer, required: Estimated tokens the plugin embeds, one per four code points of segment text.
  - `estimated_seconds` number, double, required: How long the backfill should take, at the deployment's backfill.rate or the recent throughput, whichever is slower.
  - `duration_basis` 'rate' | 'recent_backfills' | 'recent_plugin_calls', required: What the duration comes from.
  - `estimated_cost_usd` number, double: Estimated cost in US dollars, rounded up to the cent, of the target spaces that declare an input_price in the plugin manifest; a space without one adds nothing. Absent when none declares one, so the cost is unknown.
  - `confirmation_required` boolean, required: The cost exceeds backfill.max_cost_without_confirmation, so starting the backfill needs confirm_cost.

## Other responses

- `202`: The accepted backfill Operation; read it at the Location.
- `default`: Structured error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 404 unknown Corpus, 409 dry_run_required, cost_confirmation_required, idempotency_conflict, backfill_in_progress, registration_not_active or rebuild_required (the Corpus's generation predates named vector spaces), 422 invalid_schema or invalid_backfill (a space the plugin does not declare or the deployment does not enable, or an empty window), 503 storage unavailable.

---

[API](https://skmtc.dev/thevibecompany/apis/quivr-http-api.md) - [All operations](https://skmtc.dev/thevibecompany/apis/quivr-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thevibecompany/apis/quivr-http-api/revisions/4f4e30ba8f4e?raw)