Skip to main content

Backfill

Trigger a backfill of the linking graph for all documents. Useful after link key configuration changes. Poll progress via the backfill progress endpoint.

After changing link key configurations — such as classifying new fields as link keys or reclassifying existing ones — the linking graph needs to be rebuilt. The backfill endpoint scans all documents and reconstructs entity links based on the current link key set.

Backfill is serialized per organization. If a backfill is already running, the request is silently skipped. Poll the progress endpoint to monitor in-flight backfills.
POST/v1/linking/backfill

Response

Response fields (202 Accepted)

statusstringAlways "started" when the backfill is queued.
messagestringHuman-readable confirmation message.

Response (202)

{
  "status": "started",
  "message": "Backfill queued."
}

Use the progress endpoint to monitor the backfill. The running field indicates whether the operation is still in progress, and processed / total track document-level progress.

GET/v1/linking/backfill/progress

Response

Response fields

totalintegerTotal number of documents to process.
processedintegerNumber of documents processed so far.
runningbooleanWhether a backfill is currently in progress.
entities_createdintegerNumber of entity records created during this backfill.
links_createdintegerNumber of document-entity links created during this backfill.

Response

{
  "total": 540,
  "processed": 187,
  "running": true,
  "entities_created": 312,
  "links_created": 894
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Link Keys
Classify