Wanted

The Wanted page (/wanted) is Sublarr’s queue of episodes and movies that don’t yet have subtitles in your target language. Items land here automatically — you rarely add anything by hand. Sublarr scans your library, decides what’s missing against your active Language Profile, and then either searches providers immediately or schedules the search based on your pacing settings.

Where wanted items come from

Sublarr discovers missing subtitles from any source you’ve connected:

• Sonarr / Radarr instances. Periodic syncs read every monitored series and movie, then check on disk whether the target-language sidecars are present.
• Standalone watched folders. Folders configured under Settings → Connections → Standalone are scanned on the same cadence and produce wanted items for matching files.
• Webhooks (push-driven). Sonarr / Radarr Download events arrive faster than the periodic scan and add wanted items for new releases the moment they hit the library.

The languages of a wanted item follow the title’s language profile (the default profile when the title has none). When a language is removed from a series’ or movie’s profile, or the title gets a profile with other languages, the next scan removes its waiting wanted items for that language instead of searching for them forever. Items with a result or history (for example a provisional machine translation) stay.

A subtitle file that holds only a header (common for extracted ASS tracks) does not remove an episode from the list. With Automatic repair on (off by default), a full-looking sidecar that holds only signs and credits counts as missing too. The dashboard’s Missing counter counts only items without any subtitle.

The scan is incremental — only files modified since the last run are re-checked. Every sixth cycle a full scan re-validates everything to catch silent file moves and out-of-band deletions.

Status legend

Every row carries a status badge (left of the title). The colour scheme is consistent with the rest of the UI.

Status	Colour	Meaning
wanted	orange	Subtitle missing; queued for the next search cycle.
searching	blue (spinning)	Providers are being queried right now.
found	green	Subtitle downloaded and written to disk. Item disappears from the list shortly after.
extracted	teal	Subtitle came from an embedded video track, no provider needed.
failed	red	Search exhausted all eligible providers without a hit. The row keeps the last error tooltip on hover.
ignored	grey	You manually marked this item not interesting. Hidden from default views; show via the filter panel.
skipped	grey	The Wanted scanner’s eligibility filter excluded this item this cycle (e.g. slow-mode no_result cooldown, daily provider budget exhausted). Skipped items return to wanted automatically once the cooldown expires.

Manual versus automatic search

Sublarr searches automatically based on the Wanted Search scheduler job — interval and pacing live in Settings → System → Scheduler. Manual actions on the page take precedence and skip the queue:

• Search. Single-row button. Triggers an immediate provider sweep, bypassing eligibility cooldowns. Useful when a release just dropped and you don’t want to wait for the next tick.
• Process. Single-row. Searches and, if a result clears the score threshold, downloads it in one step.
• Batch Search. Toolbar button at the top. Runs Search on every row matching the current filter. Honours pacing and the per-provider rate limits — does not nuke your daily budget.
• Batch Translate. When the missing language has no provider hits, Sublarr can take the next-best embedded or sidecar track and translate it through the configured backend (Ollama, DeepL, …).
• Ignore / Un-ignore. Toggles the ignored status. Ignored items no longer count against your search quota.
• Reset search attempts. Toolbar button. Releases items that are waiting out a backoff — see Parked items below.
• Cleanup Sidecars. Toolbar button. For the extracted items, moves subtitle files next to the video whose language nobody wants for it — every wanted language of that video plus its language profile counts — into the subtitle trash. Each run is one sidecar batch, restorable from the Trash page.

The scanner state pill in the page header (scanning…, idle, N to search) reflects the global background queue, not the row you’re looking at. A spinning searching badge on a single row means that row’s manual search is in flight.

Parked items

An item that keeps finding nothing is searched less and less often, until it is only retried every few weeks. That is the right answer while the problem is the subtitle’s availability — and the wrong one once the problem turns out to have been your install. Items that burned their attempts during a provider outage or a misconfiguration keep waiting out a window that outlived its cause.

Those rows carry a Parked badge showing when the next attempt is due, so the idle part of the queue is visible without opening anything.

Reset search attempts in the toolbar releases them. It clears the attempt counter, the retry timestamp and the slow-mode marker — everything the scheduler’s eligibility filter reads — so the items are picked up on the next tick.

It also clears the error state, including the recorded error count. That count does not decide eligibility by itself, but it sets the length of the next backoff: leaving it would drop a freshly released item straight back into a long wait at its first hiccup after the recovery, which is exactly the situation you are trying to get out of. The stale error text goes too — describing a fault that has been fixed is worse than saying nothing.

Only items still in wanted are touched. A bulk action driven by a filter can easily include rows that were already found, and re-opening settled work is not what you asked for.

Slow mode

Each search that finds nothing counts as a miss and pushes the next attempt further out. Once an item has used up Max Search Attempts (Settings → Automation, default 3), it enters slow mode: it stays wanted, but is searched only about once a month. After wanted_search_max_slow_cycles (default 3) slow-mode searches that also find nothing, it is taken out of the active queue.

A search that no provider answered — every provider skipped for the moment (request limit, daily budget, API keys cooling, provider paused) or failing — is not a miss. It is booked as a temporary provider problem and does not use up the item’s search attempts.

How long the item then waits depends on why nobody answered. When every provider that did not answer was held back only by Sublarr itself — its request budget or window, a cooling key pool, a provider Sublarr auto-disabled, or an open circuit breaker — the search is simply retried after 6 hours, and the item’s error count is not raised. Only a real provider-side fault rides the escalating error backoff (6 hours, 1 day, 3 days, 7 days, then 30 days).

Automatic second chance

Sublarr can also release exhausted items on its own. Two triggers share one mechanism, the same reset as the toolbar button:

Setting	Default	Effect
wanted_revive_on_provider_change	true	When a provider is newly enabled or given a new credential, exhausted items get another chance. Switching a provider off, or saving an unchanged value, revives nothing.
wanted_revive_exhausted_after_days	0 (off)	Items exhausted for longer than this many days come back in rotation; checked once a day by the wanted_revive job.
wanted_revive_max_per_run	200	Upper limit of items one revival releases. Both triggers share it, so a large parked backlog returns in slices instead of flooding the next search cycle.

The three settings have no field in the UI; set them through the config API (PUT /api/v1/config). Each trigger can be switched off on its own: turning off the provider-change trigger leaves the age-based one running.

Filtering and grouping

The filter panel on the right narrows the list by:

• Status — any combination of the badges above.
• Language — wanted target language (e.g. show only items missing de).
• Source — Sonarr / Radarr / Standalone.
• Provider error — show only rows whose last failure was a specific provider (helps spot a single misbehaving adapter).

Episodes from the same series collapse into a grouped row by default — one row per Series · Season, with the badges aggregated. Expand a group to see individual episodes; the per-episode actions are identical to the flat-row view. Switch to flat layout via the toolbar toggle if you prefer scrolling over grouping.

Dry run — preview without writing

A dry run executes the full pipeline for a batch of wanted items — profile gates, provider search, scoring, upgrade decision — but writes nothing to disk or to the database. You get, per item, the provider that would have won, the score, the format and the exact output path.

Use it to answer “what would automation actually do here?” before letting it run, or to confirm a scoring change had the effect you intended.

Result	Meaning
found	A candidate won. The provider, score, format and target path are shown.
not_found	The search ran and nothing cleared the bar.
skipped	A pre-flight gate stopped it — the reason is given (target already on disk, slow-mode backoff, and so on).
failed	The item could not be processed, e.g. the media file is missing.

Each item’s status is restored afterwards, so a preview never leaves rows stuck in “searching”. Up to ten items per run.

Note

A dry run deliberately records no decision log — persistence is part of what it suppresses. The result is shown inline instead.

Export

Export downloads the current wanted list as CSV or JSON. The export follows the list as it is on screen, so filters apply.

Columns cover identity (title, season/episode, target language), state (status, existing subtitle, upgrade candidate, current score), and history (search count, last search, added date, last error) — enough to analyse a backlog in a spreadsheet or feed it into your own tooling.

Subtitle Automation interaction

When Subtitle Automation is on (Settings → Subtitle Automation), the Wanted scanner does more than just queue searches:

• Embedded tracks are extracted into sidecars before any provider call, so embedded German lines never trigger a paid translation.
• Foreign-track cleanup (per-series override or global toggle) runs during the same scan and deletes off-target sidecars left by the scene group.
• SDH source tolerance lets the scanner accept SDH-stripped variants when the regular variant doesn’t exist.

Each of those is documented in detail under Settings → Subtitle Automation.

Common questions

Why does an item flip back to wanted after I ran Search? The search returned no result that cleared the score threshold. Lower the threshold per language (Settings → Translation / Profiles) or pick a different provider order.

Why is Search greyed out? The row is already searching — wait for the spinner to clear. Failures auto-clear after the configured cooldown.

Where’s the search history? Per-item history lives behind the ⋯ dropdown on each row → History. Global activity (every search, download, translate, post-process) is on the Activity page.