This page explains the sweep lifecycle in detail — how Nudgarr decides what to search, when to search it, and what happens with the results.

---

A sweep is one full pass across all enabled instances. Nudgarr runs sweeps on a cron schedule (or on demand via Run Now) and during each sweep it:

1. Runs the auto-unexclude pass — any auto-excluded titles older than the configured Unexclude Days threshold are removed from the exclusions list and made eligible again before the search pipeline runs
2. Fetches the Cutoff Unmet list from each instance
3. Filters out excluded titles
4. Applies tag and profile filters (if configured)
5. Skips items already in the download queue
6. Applies cooldown — skips anything searched too recently
7. Picks up to the configured maximum from the eligible items
8. Sends search requests to the arr app in batches
9. Records each search in History with a timestamp
10. Repeats for Backlog Nudges (if enabled)
11. After the sweep completes, the import check loop polls independently to confirm successful downloads — and at the end of each import check cycle, evaluates whether any titles have hit the auto-exclusion threshold

---

Nudgarr uses a cron expression to determine when sweeps fire. The default is 0 */6 * * * — every 6 hours on the hour. You can change this in Settings, or set the scheduler to off and trigger sweeps manually with Run Now.

Key behaviours:

• No startup sweep. Nudgarr does not sweep immediately on container start. The first sweep fires when the cron expression next matches.
• No catch-up. If the container was stopped and missed several scheduled runs, those are not replayed on restart.
• Timezone-aware. Set the TZ environment variable to make your cron schedule fire in local time.

---

Before any fetching begins, Nudgarr checks whether any auto-excluded titles have aged past the configured Unexclude Days threshold. Titles that qualify are removed from the exclusions list and their search count reset to zero, making them eligible for searching again in this sweep. Manual exclusions are never touched by this pass.

If auto-exclusion is disabled (Unexclude Days = 0), this step completes instantly with nothing to do.

Nudgarr calls GET /api/v3/wanted/cutoff on each enabled Radarr instance and the equivalent on Sonarr. This returns the full list of items that have a file but have not reached the quality cutoff you configured in that app. All pages are fetched with no item cap — libraries of any size are fully covered. The complete list is what all sample modes (Random, Alphabetical, Oldest Added, Newest Added) operate on.

Any title that appears on the Exclusions list is removed before further processing. Exclusions are matched by title (case-insensitive). This includes both manual exclusions and active auto-exclusions.

If any tag or quality profile filters are configured for this instance (via the Filters tab), items matching an excluded tag or profile are removed. Filtered items never consume a search slot. See Filters for setup.

Nudgarr fetches the current download queue from each instance and removes any items whose IDs appear in that queue. Queued items are never counted against the run's maximum. If 3 of your 5 Cutoff Unmet items are already downloading, Nudgarr searches the remaining 2 eligible ones (up to your Max per Run cap), not 2 minus 3. Each skipped item is logged at DEBUG level as skipped_queued and the aggregate count appears in the INFO summary line.

Each item that has been searched before has a timestamp in the database. If that timestamp is within the configured Cooldown window, the item is skipped. The Sweep tab shows the count of items skipped for this reason in the Cooldown stat.

From the eligible items (not excluded, not filtered, not queued, not on cooldown), Nudgarr picks up to Max per Run according to the configured Sample Mode — random, alphabetical, oldest added, or newest added.

Nudgarr sends the selected items to the arr app's search endpoint in batches of Batch Size. Between batches it waits sleep_seconds plus a random amount up to jitter_seconds. This pacing prevents hammering indexers.

Every searched item is recorded in the SQLite database with the sweep type (Cutoff or Backlog), instance name, title, and timestamp. This record is what drives the cooldown check on future sweeps.

If Backlog Nudges are enabled for Radarr or Sonarr, the same process repeats for missing items using the separate Missing Max cap and Missing Added Days age filter. Backlog and Cutoff searches are independent — they have separate counters and separate history entries. See Radarr & Sonarr Backlog.

---

Nudgarr runs an import check loop on its own independent timer (default: every 120 minutes). This loop polls each instance for recently imported files and matches them against previously searched items in the database. When a match is found, the item is recorded in the Imports tab.

After each import check cycle completes, Nudgarr also runs the auto-exclusion evaluation. This checks all titles whose search count has reached the configured threshold, have no confirmed import, are not currently in the download queue, and are not already excluded. Any title meeting all four conditions is written to the exclusions table with source=auto.

Because auto-exclusion runs inside the import check loop rather than during the sweep itself, there is a timing relationship between your import check interval and your cron schedule. See FAQ & Troubleshooting for details on keeping auto-exclusion responsive.

The import loop runs regardless of whether a sweep has recently completed.

Turnaround time measures the gap between the first search timestamp (first_searched_ts) and the confirmed import. It is displayed in human-readable form: <1m, 4h 23m, 3d 14h, etc.

If the same item is imported more than once (e.g. a quality upgrade after an initial grab), an iteration counter is incremented and shown as a ×ばつ2 or ×ばつ3 badge in the Imports tab.

---

The History tab shows every search Nudgarr has triggered, most recent first. Each row includes:

• Title
• Sweep type — Cutoff or Backlog
• Instance name
• Library added date (when the item was added to Radarr/Sonarr)
• Search count (how many times Nudgarr has searched this item)
• Last searched timestamp

You can sort by any column and filter by title. The ⊘ icon on any row adds the title to the Exclusions list.

State retention (default 180 days) prunes history entries older than the configured threshold. This keeps the database from growing indefinitely and also means cooldown records are eventually cleared for very old searches.

---

The Sweep tab shows a live view of the current or most recent sweep. Each instance card is divided into two bands.

Library State

Stat	Meaning
Cutoff Unmet	Total items in the Wanted → Cutoff Unmet list
Backfill	Total monitored missing items eligible for backlog search

This Run

Stat	Meaning
Eligible	Items that passed all filters and were available to pick
Searched	Items Nudgarr sent a search request for this run
Cooldown	Items skipped — searched too recently
Capped	Eligible items not selected because the per-run limit was reached

The run indicator light blinks while a sweep is in progress and turns solid green when it completes (including all history writes).

---

Nudgarr processes each enabled instance independently and in sequence. Each instance has its own health indicator — a failed instance does not block others from being swept. Cooldown tracking is per-instance, so searching an item in your main Radarr does not affect its cooldown state in a secondary Radarr.