Train your bot

Training turns your uploaded documents into a knowledge base the bot can search. Until a bot is trained at least once, it cannot answer questions.

Bot status reference#

Every bot has a status shown on the Dashboard card and on the bot detail page. The status tells you whether the bot is ready for chat and what action to take next.

Status badge variants on bot cards

Status transitions#

NO_DATA -> (upload) -> UNTRAINED
UNTRAINED -> (train) -> PENDING -> READY
READY -> (change documents) -> OUTDATED
OUTDATED -> (retrain) -> PENDING -> READY
PENDING -> (training fails) -> previous status

How to start training#

Open the bot's Source settings tab and click Train Bot. If the button is disabled, see Cannot train.

What happens, in order#

1. Prepare

   Pegasus computes which documents are new, changed, or removed compared with the last training. This delta drives the rest of the job.

2. Parse

   The chosen parser reads each new or changed document and extracts Markdown.

3. Embed

   Markdown is split into chunks; each chunk is embedded into a vector and stored in the bot's index.

4. Commit

   Pegasus marks the bot READY and emits a completion event. The Train button label resets.

Watching progress#

While the bot is PENDING, the Train button is replaced by live status:

• "Waiting in queue (position )" - other jobs are ahead of you.
• "Next in line" - your job starts as soon as a slot opens.
• "Preparing documents..." - Pegasus is computing the delta.
• "Parsing documents..." - text extraction is running.
• "Embedding chunks..." - Pegasus is building the vector index.
• "Retrying (attempt N)..." - a transient error happened and Pegasus is retrying automatically.

Training status: queued and running

Cancelling a training#

While PENDING, a Cancel button appears.

• If queued: Pegasus removes the job from the queue immediately.
• If running: Pegasus stops at the next safe checkpoint, so the current file finishes parsing or embedding first.

The bot returns to its pre-training status.

First training vs retraining#

• First training parses and embeds every document, so it is usually the slowest run.
• Retraining processes only the delta: added, removed, or changed files.

That delta-based behavior is why later runs are often much faster.

OUTDATED bots and when to retrain#

A bot enters OUTDATED when its documents change after a successful training.

• Uploading a new document to a READY bot marks it OUTDATED.
• Deleting a document from a READY bot marks it OUTDATED.
• Chat, embed, and API traffic can still use the last trained version.

What changes while the bot is OUTDATED:

• The bot still answers questions.
• The answers do not include the latest document changes until you retrain.
• You can keep editing the knowledge base before retraining.

Retrain immediately when the change is critical, such as removing incorrect material. For additive or batch edits, it is fine to wait and retrain once after you finish the set of changes.

The OUTDATED state has no time limit. A bot can remain OUTDATED indefinitely, but its answers will keep using older context until the next successful training run.

Can you chat in each status?#

If you try to chat with a bot that is not ready, Pegasus shows "Bot is not ready for chat." See Bot is not ready for help.

Training failures#

If a training run fails:

• The bot reverts to its previous status.
• "Last error: " appears on the bot detail page.
• The training does not consume the full credit cost; only partial work is billed.

See Training failed for deeper troubleshooting.

Daily credit limit#

Training uses the same daily credit pool as chat. If you hit the cap, you see "Daily credit limit reached. Cannot train now. Resets at midnight UTC."

Wait for reset or upgrade your plan before running the job again.