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. Fetches the Cutoff Unmet list from each instance
2. Filters out excluded titles and items already in the download queue
3. Applies cooldown — skips anything searched too recently
4. Picks up to the configured maximum from the eligible items
5. Sends search requests to the arr app in batches
6. Records each search in History with a timestamp
7. Repeats for Backlog Nudges (if enabled)
8. After the sweep completes, the import check loop polls independently to confirm successful downloads

---

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.

---

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.

Any title that appears on the Exclusions list is removed before further processing. Exclusions are matched by title (case-insensitive).

Nudgarr fetches the current download queue from each instance and removes any items whose IDs appear in that queue. This happens silently — 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 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 On Cooldown stat.

From the eligible items (not excluded, 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.

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. For each enabled instance it displays:

Stat	Meaning
Cutoff Unmet	Total items in the Wanted → Cutoff Unmet list
On Cooldown	Items skipped because they were searched too recently
Searched	Items Nudgarr sent a search request for this run

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.