Which features need something extra
The table above is per credential. This one is per feature — for when you have found something in Kustos and want to know what it will cost you before you turn it on.
Everything not listed here needs nothing beyond a free key. That is most of Kustos: collections, cleanup, arr rules, overlays, watch tracking, artwork scraping and auto-create all run on free credentials.
Needs AI
Three separate keys, deliberately, so none can spend another's quota. All three work on a free tier.
| Feature | Which key | Without it |
|---|---|---|
| Textless detection in auto-create — knowing which artwork has the title baked in | Gemini Vision | Detection is off and art selection falls back to textless-first. Auto-create still works. |
| Per-person suggestions, and the Plex rows built from them | Suggestions AI | No suggestions. Everything else is unaffected. |
| The in-app assistant | AI Helper | The assistant is unavailable. |
The one that actually consumes a lot
Textless detection is the hungry one, and it is worth understanding before you point it at a large library.
It asks about every candidate poster for every title on the first sweep, one call each, starting on free keys and moving to a paid one if you have added one. A large library fills in over several nights. Turn it off with Check whether candidate art already has a title on it in Automate Artwork; auto-create then trusts TMDB's own textless flag.
Title-card text detection is separate, paid-only and off by default. A paid Gemini key allows 250 interactive requests per day, per model, and one request checks one card, so a re-check of ~6,600 title cards would take about 26 days. That re-check uses the Batch API instead: a separate allocation, half the price, with a 24-hour turnaround. Submitting a batch, polling it and fetching the results are three separate calls that can happen at different times, because a batch outlives any one pass.
The other two AI jobs are cheap: suggestions are roughly one call per person per day, and the assistant costs nothing until you use it.
When a key runs out mid-run
Kustos does not stop when a free-tier key hits its daily limit. Two mechanisms, and they are different things:
| Spare keys | Extra keys attached to the same slot. Kustos moves onto one when the key in use is exhausted, and back the next day. Add them on Connections — the card for a key offers Add a spare key, and names it correctly for you. |
| A named fallback | On an AI card: when this key is rate-limited, retry on the one named here. Every model on the current key is tried first, then that one. |
The fallback is NAMED rather than "any other key" on purpose. The free tier meters per model, so a key that is out on one model may be fine on another — which is why the chain tries every model on the current key before moving. And naming the next key means free quota is spent before paid, rather than a rotation picking whichever key it happened to reach first.
Needs a paid account somewhere else
| Feature | Needs | The free way round it |
|---|---|---|
| Simkl custom lists as a collection source | Simkl PRO or VIP — only for the person whose lists are being read | Use an MDBList list instead. Same job, free tier. |
| Trakt's VIP-only API | One linked person with Trakt VIP — not you, and not the registration, which is free | Nothing equivalent for those endpoints, but everything else Trakt does works without it. |
| "Visible on" — which Plex surfaces a collection appears on (Recommended, your Home, friends' Home) | Plex Pass | None. On a server without Plex Pass, Kustos still stores the choice and Plex ignores it. |
| Plex Library View in item metadata | Plex Pass | None. |
Trakt's rate limit is worth knowing even with VIP. A build-all that pulls Trakt for every watch-filtered collection is what trips the non-VIP limit — a single sensible pull never does. Kustos caches one merged aggregate per five-minute window so a whole run shares it, which is why this is rarely a problem in practice.
Free, but metered
| Service | The limit |
|---|---|
| MDBList | A daily budget. MDBList lookups per pass in Settings → General caps how much one pass may spend, so a big run cannot exhaust the day. |
| Google AI free tier | Metered per model, which is why running out on one model does not stop the others. See the free limit. |