# Background jobs

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


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:

1. **Start** the job. The API answers `202 Accepted` right away.
2. **Poll** the resource with `GET` every few seconds until it reaches a final status.
3. **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

```bash
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](/developers/docs/rate-limits).
- 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](/developers/docs/uploads).
- **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](/developers/docs/gedcom).
- **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](/developers/docs/idempotency).

Canonical: https://kleiobase.com/developers/docs/background-jobs