# Uploading Records

Supported files, how the AI reads and extracts your documents, and how to review and confirm a record.


Uploading is the first step in turning a scan into a connected family history. You add an image of a document, KleioBase reads it with AI, and you review and confirm what it found. This article covers which files work, how to upload them, what the AI pulls out, and how to review and confirm a record. If you are new, start with [Getting Started](/docs/getting-started) first.

The [90-second walkthrough](https://www.youtube.com/watch?v=SoeGIDvgtWs) shows the whole upload and review pass on a real record, if you would rather watch it than read it.

## Where uploading happens

Uploading happens in the upload workspace at [/upload](/upload). The workspace is tab-based: each record you add gets its own tab with a small status dot, so you can have several records in progress at once and move between them.

When more tabs are open than fit across the screen, scroll the strip with your mouse wheel, or hold the mouse button down on it and drag sideways. Searching for a record from the search bar at the top of the app also opens it here, in a tab.

There are three ways to add an image:

1. Drag and drop a file onto the dropzone.
2. Click the dropzone to open a file picker and choose a file.
3. Paste an image directly from your clipboard with Ctrl/Cmd+V.

All three add one image at a time. To add a batch in one go, use a .zip on the Archivist or Professional plans, or a PDF on any plan (see below).

### Adding a record when tabs are already open

The large dropzone appears only on an empty workspace. Once a record is open in a tab, the workspace fills with that record and the dropzone is gone.

To add another record from there, use the small upload icon **just after your last tab**, in the strip along the top. It opens the same file picker. Once you have enough tabs open to fill the strip, the icon stays pinned at the right-hand edge rather than scrolling away with them, so it is always reachable. Clipboard paste does not work once a tab is open.

You can also drag a file anywhere onto the workspace and drop it, the same as on the empty workspace.

Closing all your open tabs also brings the large dropzone back.

### Supported files

KleioBase reads JPG, PNG, and PDF files. Images are up to 10 MB each. A PDF can be up to 50 MB and 100 pages - dropping one opens a page picker where you choose which pages to bring in, and each page you pick becomes its own record, just like uploading that page as a JPG. WebP, GIF, HEIC, and TIFF images are not supported.

GEDCOM files are not uploaded here. They go through a separate GEDCOM import flow. See [Importing & Exporting Data](/docs/importing-and-exporting).

### Bulk upload with a .zip

On the Archivist and Professional plans you can upload a .zip of JPG and PNG images. KleioBase extracts the images from the zip and adds them as records. Any non-image files inside the zip are skipped.

### Uploading a PDF

Unlike a .zip, a PDF works on every plan - it is a file format, not a bulk-import convenience, and it does not grant any extra credits.

Drop a PDF onto the workspace, or pick one from the file picker, the same way you would an image. It opens a page picker in its own tab, showing one tile per page. Click anywhere on a tile to tick it, use Select all for the whole file, then click Add. Each page you add becomes its own record and moves through the same Uploaded → Processing → Review → Confirmed states as any other record.

Pages are added one at a time: the first page starts uploading while the rest are still being prepared, so tabs appear as the work goes. When you add more than one page, KleioBase keeps you on the page picker until the whole run has finished, with the Add button counting it off ("Adding 3 of 40..."), and moves you to the first added page at the end. Adding a single page takes you straight to it. If one page cannot be prepared, that page alone is marked in red on its tile with a Retry button, and the rest of your selection carries on.

- **Limits:** a PDF can be up to 50 MB and 100 pages.
- **Adding pages is free.** Like any upload, adding pages from a PDF does not use your credits. Processing a page afterward costs 1 credit, the same as any other record (5 for a deep scan). If you tick more pages than you have credits left to process, KleioBase asks you to confirm before adding them.
- **A page you add is just a record.** Once it is in, it behaves exactly like an image you uploaded yourself - the same context and region boxes before you process it, the same review, the same credits. There is nothing about it to set or remember.

The PDF itself stays in your browser the whole time. It is never uploaded to or stored on our servers - only the pages you pick, once rendered, become records. Clipboard paste (Ctrl/Cmd+V) does not work for PDFs, only for images; use drag-and-drop or the file picker instead.

## Uploading is free, processing is not

This is the most useful thing to understand about the workspace. Adding images is free and fast, so you can drop in many at once without using up anything. What uses your credits is processing - the AI extraction step that reads each document. You decide which uploaded records to process and when, so you stay in control of your usage.

## The status lifecycle

Each record moves through a series of states, shown by the dot on its tab. Here is what each state means and what you can do in it.

| Status | What it means | What you can do |
| --- | --- | --- |
| Uploaded | The image is added but not yet read by the AI. | Add optional context, draw region boxes, then process. |
| Processing | The AI is reading the document (about 1 to 3 minutes). The record cannot be edited while this runs. | Wait. You can switch to other tabs meanwhile. |
| Review | Extraction is ready and the fields are editable. | Read the transcription, fix mistakes, then Confirm. |
| Confirmed | Profiles have been created and the record is read-only. | Follow the links into your knowledge base. |
| Failed | Something went wrong; an error is shown. | Click Retry to try again. |
| Waiting after an AI outage | The AI service was briefly unavailable. The record is not marked failed and no credit was spent. | The record goes back to its pre-processing state with a note at the top of the pane. Press Process Record when you are ready. |

## Before you process: context and regions

While a record is in the Uploaded state, you can help the AI before it reads the page.

- **Context:** type optional notes about the document, such as its language, the place it comes from, or its approximate year. This guides the AI and improves accuracy.
- **Regions:** draw boxes directly on the image to point the AI at specific areas. This is useful when only part of a page is relevant or when the layout is dense.

### Deep scan

Before you process, you can turn on deep scan with a checkbox. A normal scan uses 1 credit. A deep scan uses 5 credits instead of 1, because it reads the document with a stronger model that spends much longer working through difficult handwriting. The checkbox shows how many credits you have left so there are no surprises. Use it when a normal scan returns names or words that are clearly wrong.

## What the AI extracts

When you process a record, the AI reads the document and produces a structured result. It extracts:

- A display name for the record, in your chosen output language.
- A transcription in the document's original language and script. This part is never translated.
- A flowing narrative that explains the record, in your chosen output language, written from the structured fields so it always matches them.
- The record type, such as birth, marriage, death, census, immigration, military, will, or letter, among others.
- The document's main event, including its date and place.
- Every named person, with their role, names, dates, places, occupation, and other details.
- Family units such as spouses, parents, and children.
- Witnesses and associates mentioned in the document.

### Choosing the output language

By default, KleioBase produces the translation, narrative, display name, and structured details (names, places, occupations) in English. If you work mostly in another language, you can change this once and it applies to every record you process from then on. Go to [Account & Preferences](/settings/account) and set **Default language for transcription/translation**. The change is saved as soon as you pick it. The original-language transcription is never affected; it always reflects the document as written. Existing records keep the language they were processed in; the setting applies to new processing only.

When processing finishes, the record enters the Review state. This is where you check the AI's work before it becomes part of your knowledge base.

1. Read the transcription and the list of extracted people, and compare them against the image.
2. Fix anything the AI misread. You can edit fields and change the record type, and edit the narrative (see below). Every person has a separate maiden (birth) name field, so you can add a birth surname the document does not state if you know it from elsewhere.
3. Exclude any person you do not want to keep. For example, if a name is too unclear to trust, you can disable that person so they are not added. When the AI finds people who look like officials or witnesses rather than subjects of the record (a clerk, a physician, a registrar), it flags them at the top of the list with a one-click option to leave them all out.
4. When the result looks right, click Confirm.

### Editing the narrative

The narrative is written from the structured fields, so it always stays in step with them. The parts shown on an amber background are placeholders - names, dates, and places that are filled in automatically from the fields above. The plain text between them is ordinary prose you can change.

- To correct a name, date, or place, edit the matching field above. The narrative updates to match.
- To reword the surrounding sentences, click Edit on the narrative and type. Hover any amber placeholder to see the exact value it will show.
- Each placeholder behaves as a single unit: the arrow keys step over it and one press of Delete removes the whole thing. To add a placeholder yourself, type it (for example a person's name placeholder) and close the brace, and it turns amber.

### What confirming does

Confirming commits the record to your knowledge base. It:

- Creates a new person profile for each kept person, or links to existing profiles where they already exist.
- Links the record to each person with their role in the document.
- Records the family relationships and the witnesses you kept.
- Starts duplicate matching in the background.

After you confirm, you are pointed toward your [knowledge base](/docs/knowledge-base), where the new and updated profiles appear.

## Limits and usage

Processing draws from your plan's monthly credits (a normal scan uses 1, a deep scan uses 5). The monthly amounts are:

| Plan | Credits per month |
| --- | --- |
| Explorer | 10 |
| Researcher | 100 |
| Archivist | 500 |
| Professional | 1500 |

The usage indicator in the header shows how many of your credits you have used. It turns amber and then red as you approach the limit. If you run out, you can buy pay-as-you-go credit packs or wait for your monthly reset - the 1st of the month on the free plan, your subscription's monthly anniversary on paid plans. See [Plans & Billing](/docs/plans-and-billing) for details.

### Profile limit

Confirming can be blocked if it would push you past your plan's person limit:

| Plan | Person limit |
| --- | --- |
| Explorer | 200 |
| Researcher | 2,000 |
| Archivist | 10,000 |
| Professional | Unlimited |

If you hit this, either remove some people from the extraction before confirming or upgrade your plan.

## Records waiting for review

A record that has been read but not confirmed does not belong to your knowledge base yet. Nothing from it appears under People, Places or the family tree until you confirm it.

Your dashboard shows a **Waiting for review** card whenever you have records in that state, with how long each one has been waiting. The link on that card opens them all in the upload workspace, one tab each, so you can work through them in a sitting. If a record has been sitting there for a day or two we may also email you once about it, and you can reply to that email if something on the review screen stopped you.

## Troubleshooting

**Processing was interrupted.** If you close the tab or the browser while a record is processing, the work keeps running on the server, but the workspace shows the record as interrupted when you return. Do not click Retry straight away - Retry starts a fresh extraction and uses another credit. Instead, give it a minute or two and open the record again from your knowledge base's Records tab (or the search bar at the top of the app). If the extraction finished, the record opens in Review with the result, at no extra cost. Use Retry only if the record actually failed.

**A record failed.** Failed records show an error and a Retry button. Try again, and if a normal scan keeps returning poor results on difficult handwriting, turn on deep scan before retrying.

**"Our AI service was briefly overloaded."** This is not a failure. The AI service was unavailable for a moment, so nothing was extracted and no credit was spent. The record goes back to the state it was in before you pressed Process, with that note at the top of the pane, and you can press Process Record again in a few minutes. You do not need to re-upload anything.

**"Upload throttled - click Retry."** Adding many pages at once (selecting every page of a long PDF, for example) can hit the upload rate limit, and any page that did not get through is left in its tab with this message. Wait about a minute and click Retry on each of those tabs - the page uploads again from the copy the workspace is still holding, so you do not have to pick it from the PDF a second time. Do this before closing the tab or reloading the page: either one discards the rendered page, and you would have to open the PDF and pick it again.

**A page in the PDF picker says "Not added."** That page could not be prepared in your browser, so it never left the picker and has no tab of its own. Nothing else in your selection was affected. Click Retry on that tile to prepare and add just that page. This is a different problem from a page that got a tab and then failed to upload - that one is the throttling message above, and you retry it from its tab.

**Names came back wrong.** This is the main signal to use a deep scan. Adding context about the document's language and place also helps.

**"We're not confident in this transcription."** This banner appears at the top of the review pane after a deep scan when the AI flagged at least one name it was not sure it had read correctly. The extraction is still there and still usable; the banner is asking you to check every name and date against the image before you confirm. Individual names the AI was unsure about are also tagged "verify against image" next to the name.

The warning is a useful hint rather than a guarantee. When it appears, the extraction really is weaker on average, but it does not catch every bad read - so it is worth checking names against the image even on a record that was not flagged.

**Nothing happens when I drop a file.** The workspace quietly ignores files it cannot read. Check that the file is a JPG or PNG no larger than 10 MB, or a PDF no larger than 50 MB with 100 pages or fewer - WebP, GIF, HEIC, and TIFF files are not supported.

**I dropped several files and only one appeared.** The dropzone and the file picker take one image at a time, so a batch drop of images adds only the first file. Add images one by one, use a .zip on the Archivist and Professional plans, or bring in many pages at once with a single PDF on any plan (see [Uploading a PDF](#uploading-a-pdf) above).

**I cannot see the dropzone.** It only shows on an empty workspace. If you have a record open in a tab, drag your file anywhere onto the workspace, or use the small upload icon just after your last tab. See [Adding a record when tabs are already open](#adding-a-record-when-tabs-are-already-open).

## What happens next

After you confirm, duplicate matching runs in the background, and match suggestions appear a little later as the system compares the new people against the rest of your knowledge base. To review and act on those, see [Finding & Merging Duplicates](/docs/finding-duplicates).


## Walkthrough transcript

The narration of the walkthrough video linked above, as text.

You have just uploaded a new record. Before you process it, two things are worth doing.

Most register pages hold more than one record. Drag a box around the entry you want, and only that one gets read. Everything outside the box is ignored.

Then add anything you already know. A place, a year, a family name. It does not need to be complete. It helps resolve handwriting that could be read more than one way.

DeepScan reads the page with a stronger model. It costs five credits instead of one, and on a hand like this one, it earns them. Then click process.

You get the transcription in the original language, a translation, and the details pulled out separately. Read them before you accept them. If you find anything that is wrong, you can correct it here.

Clicking confirm saves the record and the people in it. Matching runs separately in the background. KleioBase never merges anyone on its own.

When it finds someone who might already be in your tree, it shows you both side by side with the evidence, and you decide whether to accept or dismiss the match. You can also ask the Research Companion about the match and make it accept it for you.

That is just one record. Every other one works the same way.

Canonical: https://kleiobase.com/docs/uploading-records