Poll a job submitted via GET or PUT /v2/config/. Jobs are scoped to the authenticated Agent; an unknown or unowned job_id returns 404.

Three kinds of job are polled here. They share this response but not a lifecycle, a result shape, or a set of failures — so read the section for the one you submitted.

Both import modes report type: import and the response never restates the mode. Tell them apart by result: only a validate carries result.status.

Any job can also end at failed, from any non-terminal status. Then failure_reason is the slug to branch on and failure_detail the sentence to show a person — see ConfigJobFailureReason for all 14 and what to do about each.

Export

Builds the archive in the background. Nothing about the Agent changes.

completed gives a temporary download link in result.url, minted fresh on every poll, so it is never stale — poll again rather than re-exporting if one expires. result.secrets lists the client_secret variable names the snapshot needs, each null; that is the list to fill in for the import, and it needs no download.

The one failure peculiar to export is archive_expired: the export itself succeeded, but the archive was removed from storage before you polled. The job row underneath is still completed; this response reports failed rather than hand you a URL that 404s.

Import — mode: validate

The default, and where every import should start. Nothing is ever written, whatever the verdict.

The job begins at waiting_for_upload and moves on by itself once the archive lands at the upload.url you were given — a validate needs the upload too, since the answer is in the archive.

It reaches completed even when the answer is bad; the verdict is result.status, valid or blocked. result.changes reports what an apply would create, update and delete, per section and with names — including knowledge.articles.delete, the number of articles the full replace would remove from this Agent. On a selective import result.selection reports what the include closure actually dragged in and which references it could not resolve.

Run this before every apply. It is the only place the destructive half of an import is enumerated before it happens.

Import — mode: apply

Writes the snapshot to the Agent. This is the destructive direction, and the one you must ask for by name.

Same lifecycle as a validate: it waits at waiting_for_upload for the archive, and nothing is read or written before that lands — so a job sitting there has changed nothing and costs nothing to abandon.

completed gives result.articles (upserted / deleted), result.indexing, and result.post_apply_blockers — empty is the healthy answer there; a non-empty list means the import committed but left something broken. warnings lists what the import did not do, without failing.

Two failures need different handling from the rest. preflight_failed means the target Agent cannot serve the snapshot: every blocker is in result, and nothing was written. partially_applied means the opposite — the run died after the configuration phase committed, so the Agent holds part of the snapshot and a blind retry is unsafe.

Polling

Poll every 5 seconds for the first minute, then every 15. An import can wait minutes for its upload to be noticed and run for hours on a large knowledge base; progress moves while it does, and a job that keeps reporting is never timed out for being slow.