-
Notifications
You must be signed in to change notification settings - Fork 0
How Nudgarr Works
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:
- Fetches the Cutoff Unmet list from each instance
- Filters out excluded titles and items already in the download queue
- Checks Radarr availability thresholds — movies that haven't reached their minimum availability are skipped
- Applies tag and quality profile filters — items matching an excluded tag or profile are skipped
- Applies cooldown — skips anything searched too recently
- Picks up to the configured maximum from the eligible items
- Sends search requests to the arr app in batches
- Records each search in History with a timestamp
- Repeats for Backlog Nudges (if enabled)
- 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
TZenvironment 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.
For Radarr instances, Nudgarr checks each movie's isAvailable flag before including it in the sweep. Movies that haven't reached their minimum availability threshold — as configured in Radarr — are silently skipped. Nudgarr resolves availability from physicalRelease → digitalRelease → inCinemas in that order. This applies to both Cutoff Unmet and Backlog sweeps. Sonarr has no equivalent concept.
If the instance has any excluded tags or excluded quality profiles configured in the Filters tab, Nudgarr removes items that match before cooldown runs. Items are checked against the excluded tag set first, then the excluded profile set — each match is logged independently at debug level. Filtered items are never counted against the run's maximum and do not appear in History.
See Tag & Quality Profile Filters for full details.
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 two sections:
Library State — reflects the current state of your library as reported by Radarr and Sonarr:
| Stat | Meaning |
|---|---|
| Cutoff Unmet | Total items in the Wanted → Cutoff Unmet list |
| Backfill | Total missing items eligible for Backlog Nudge searches |
This Run — what happened during the most recent sweep:
| Stat | Meaning |
|---|---|
| Eligible | Items that passed all filters and were available to search |
| Searched | Items Nudgarr sent a search request for |
| Cooldown | Items skipped because they were searched too recently |
| Capped | Eligible items not searched because the per-run cap 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.