7. Fetching
Before the plugin can show you characters, a timeline, or any other X-Ray info, it needs to scan the book with an AI model and build a local database. That process is called fetching. There are five ways it happens: a full manual fetch, a manual merge, automatic background fetching, targeted inline fetching, and series context fetching.
The first time you use the plugin with a book, it needs to run a full fetch. This will happen automatically in the background if you have auto-fetching enabled (it is enabled by default), but you can also run it manually:
- Open the book and go to Tools Menu → X-Ray → Update X-Ray Data.
- The plugin sends your book's text to the AI — up to your current page in Spoiler-free mode, or the whole book in Full Book mode (see Spoiler Protection for more details).
- It takes roughly 30–60 seconds depending on book length and your connection.
- When it's done, it will notify you and save the data locally.
After this, you don't need an internet connection to browse characters, the timeline, or any other X-Ray data for that book (up to the page you fetched up to if using Spoiler-free mode). Everything is stored in a cache file on your device.
If Duplicate Check is enabled under settings, the plugin will immediately check for duplicate characters and locations once the fetch is complete, prompting you to review and merge them.
Note
After you do an initial fetch, this button will merge updates from the chapters you've read since the last fetch.
Auto-fetching does the merge update automatically in the background as you read. Every time you enter a new chapter, the plugin silently checks whether that chapter is already in your data. If it isn't, it kicks off a background merge fetch without showing any dialogs or interrupting your reading.
The plugin won't trigger a background fetch if:
- You're offline
- No API key is configured
- The chapter is already in your cached data
- The chapter is front or back matter (prefaces, acknowledgements, indices, etc.)
- You're within the cooldown window of the last fetch (see Frequency Settings)
- The chapter has already been attempted 3 times this session (prevents API hammering on persistent failures)
You can control how aggressively the plugin fetches in the background. Go to Tools Menu → X-Ray → Settings → Content & Fetch Settings → Auto X-Ray Settings → Frequency.
| Mode | What it does |
|---|---|
| Ultra | Checks every N pages you configure (mid-chapter) |
| Aggressive | Fetches on every new chapter with no cooldown |
| Balanced (default) | Fetches at most once every 5 minutes |
| Economical | Fetches at most once every 15 minutes |
| Sparse | Fetches at most once every 30 minutes |
| Disabled | No background fetching at all |
Which mode should I use?
- Ultra is best if you want real-time lookups inside the current chapter, but it may consume more battery and hit API limits faster.
- Balanced is a good fit for most readers. It keeps your data reasonably fresh without hitting rate limits or draining the battery.
- Aggressive is best for short reading sessions where you want the data caught up immediately.
- Economical or Sparse are worth trying if you're on a slow connection, watching your API quota closely, or reading on an older device where battery life is a concern.
- Disabled makes sense if you prefer to always fetch manually, or if you're reading a book where you already have complete data (e.g., Full Book mode on a re-read).
Note
If chapters get skipped due to the cooldown or being offline, they'll be picked up the next time a fetch does run, either automatically or when you trigger one manually. Additionally, if Duplicate Check is enabled, it will scan for duplicates in the background and prompt you to review them the next time you open the Characters or Locations menu.
Sometimes you might encounter a name or term that was missed during the initial or background fetches. Instead of running a manual update for the whole chapter, you can fetch just that specific word:
- Select the word in the text (long-press).
- Tap the X-Ray button in the popup menu.
- If no data is found, the plugin will ask if you want to look it up using AI.
- Tap Fetch.
- Speed: Usually takes less than 15 seconds.
- Integration: Once fetched, the new entity is automatically added to your Characters or Locations list and saved to the cache, just like any other fetch.
This is the most efficient way to fill in gaps for minor characters or specific world-building terms as you encounter them.
For books that are part of a series, the plugin can fetch recap data for all preceding volumes:
- Detection & Request: The plugin automatically detects the series name and current volume index (Book 2 or later) from metadata. If no metadata exists, it uses the AI model to identify the series.
-
Caching: The recap data is fetched per-book for all prior volumes and cached under a global series slug (e.g.
settings/xray/series/my_series_name.lua). - Network Optimization: The plugin checks the local series cache first. If recap data for any preceding volume is missing, it connects to the network to fetch the summary for the missing books one by one. If all books are already cached, the merge completes offline instantly.
- Silent vs. Interactive: When you first open a series book, it prompts you interactively. You can also trigger a manual fetch from Tools Menu → X-Ray → Settings → Content & Fetch Settings → Series Context → Fetch / Refresh Series Context or disable it completely under Settings.
When you trigger "Find Mentions" for an entity, the plugin performs an asynchronous scan of the book's text.
- Wait to Complete: When triggering a manual mention scan, you must keep the menu open until the scan finishes. Navigating away or closing the menu before it's done will interrupt the process.
- Persistence: Once a scan for an entity is complete, the results are saved to the cache and don't need to be manually scanned again.
- Incremental Growth: Every time you enter a new chapter, the plugin silently scans that chapter in the background for any entities you have previously "activated." This ensures your mention lists stay up to date without further manual scans.
- Spoiler Protection — how the plugin decides how much of the book to send to the AI.
- AI Providers & Models — which AI backends you can use and how to handle rate limits.
- Get Started — how to install the plugin and set up your API keys.