API documentation

Background jobs

Record processing, GEDCOM import and GEDCOM export run in the background. How to start them, poll them and act on the result.

Last updated October 16, 2026

Three kinds of work take too long for one request: processing a record, importing a GEDCOM file and exporting one. They all follow the same pattern:

Start the job. The API answers 202 Accepted right away.
Poll the resource with GET every few seconds until it reaches a final status.
Act on the result.

The API never sends email or pushes a notification when a job finishes. Polling is how you find out.

Job	Start	Poll	Done when
Record processing	`POST .../records/{record_id}/process`	`GET .../records/{record_id}`	`status` is `review` or `failed`
GEDCOM import	`POST .../gedcom/imports`	`GET .../gedcom/imports/{import_id}`	`awaiting_confirmation`, then after confirm `completed`, or `failed`
GEDCOM export	`POST .../gedcom/exports`	`GET .../gedcom/exports/{export_id}`	`status` is `ready` or `failed`

Polling

curl https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/gedcom/exports/EXPORT_ID \
  -H "Authorization: Bearer kb_live_YOUR_KEY"

Every few seconds is enough. Each poll is a normal request and counts against your rate limit.
On a 429, wait the Retry-After seconds before the next poll.
A failed GEDCOM job carries an error that says why.

Acting on the result

Record processing: read the extraction, correct it if needed, then confirm. See Uploads and processing.
GEDCOM import: at awaiting_confirmation, check the analysis and confirm or cancel. Confirming starts a second background step; poll again until completed. See GEDCOM import and export.
GEDCOM export: at ready, download from download.url within 5 minutes, or poll again for a fresh URL.

Retrying a start

Send an Idempotency-Key when you start processing, confirm an import or start an export, so a retry after a timeout cannot start a second job. Uploads (POST .../records and POST .../gedcom/imports) are not idempotent. If a record upload times out, list your records before you retry. A duplicate GEDCOM upload is harmless: an import you never confirm expires after about an hour. See Idempotency.

Building a product on KleioBase? Contact us.