Skip to main content

Linking 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

Request

curl -X POST https://api.talonic.com/v1/linking/backfill \
  -H "Authorization: Bearer $TALONIC_API_KEY"

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.

Frequently asked questions

How long does a backfill take?+
Duration depends on the number of documents in your workspace. Poll the progress endpoint to track completion. The backfill processes documents in batches.
Is classification automatically triggered during backfill?+
No. Backfill only rebuilds entity links using the current link key set. To classify new fields as link keys, call the Classify endpoint first, which will trigger its own backfill if new keys are found.
What happens if I trigger a backfill while one is already running?+
Backfills are serialized per organization, so the second request is skipped rather than queued. Check GET /v1/linking/backfill/progress: when running is false you can trigger a fresh backfill.

Related

Link Keys
Classify