Skip to main content

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.

Overview​

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 runs up to three independent pipelines in sequence:

  1. Queue depth check — skips the entire sweep if the total download queue across all instances meets or exceeds the configured threshold (if enabled)
  2. Auto-unexclude pass — removes auto-excluded titles that have aged past the configured threshold before any searching begins
  3. Cutoff Unmet pipeline — tells each Arr to search for better quality versions of files that don't meet the quality profile cutoff
  4. Backlog pipeline — tells each Arr to search for missing movies and episodes (if enabled)
  5. CF Score pipeline — tells each Arr to search for better-scored releases on files that are already at the right quality tier but below the custom format score cutoff (if enabled)

Each pipeline is independent. They run in sequence during the same sweep but use separate caps, separate history entries, and separate counters on the Sweep tab.

Scheduling​

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.
  • Maintenance Window. Scheduled sweeps can be suppressed during a defined time window. Run Now is never affected.
  • Timezone-aware. Set the TZ environment variable to make your cron schedule fire in local time.

The sweep lifecycle in detail​

Step 1 — Queue depth check (if enabled)​

If Queue Depth is enabled in Advanced, Nudgarr fetches the current download queue count from each enabled instance before doing anything else. The counts are summed across all instances. If the total meets or exceeds the configured threshold the sweep is skipped entirely -- no auto-unexclude pass, no pipeline work, nothing. A log entry is written and the status bar updates to show the skip. The next scheduled sweep will check again from scratch.

If an instance fails to respond to the queue check it contributes 0 to the sum and a warning is logged. The sweep proceeds based on whatever total could be retrieved.

Step 2 — Auto-unexclude pass​

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.

Step 3 — Cutoff Unmet pipeline​

If the Cutoff Unmet pipeline is enabled for an app (on by default), Nudgarr fetches the full Cutoff Unmet list from each enabled instance. This returns every item that has a file but has not reached the quality cutoff defined in its quality profile. All pages are fetched with no cap — libraries of any size are fully covered.

The full filter chain then applies: exclusions, tag and profile filters, queue skip, cooldown. From the eligible items, Nudgarr picks up to Max per Run according to the configured Sample Mode and tells the Arr to search for each one.

If the Cutoff Unmet toggle is off for an app, this pipeline is skipped entirely for that app. Queue IDs are still fetched so Backlog and CF Score can skip items already downloading.

Step 4 — Backlog pipeline (if enabled)​

If Backlog is enabled for an app, the same process repeats for missing items using the separate Missing Max cap. For Radarr, the Missing Added Days age filter also applies. Sonarr has no equivalent age filter.

Backlog and Cutoff Unmet searches are independent — they have separate counters and separate history entries. See Radarr & Sonarr Backlog.

Step 5 — CF Score pipeline (if enabled)​

If CF Score is enabled, Nudgarr reads from its pre-built index of monitored files where the custom format score is below the quality profile cutoff. This index is built and maintained by a separate sync process (the CF Score syncer) and is not affected by whether a sweep is running.

CF Score items go through the same cooldown and exclusion filters as other pipelines, capped at the configured CF Score Max per Run. Items already in the download queue are skipped. Nudgarr then tells each Arr to search for a better-scored release.

See CF Score for full details on how the index is built and what "below cutoff" means.

Step 6 — Record history​

Every item searched across all three pipelines is recorded in the database with the pipeline type, instance name, title, and timestamp. This record drives the cooldown check on future sweeps. In the History tab, Cutoff Unmet items appear as Cutoff, Backlog items as Backlog, and CF Score items as CF Score.

Import tracking and auto-exclusion​

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 with the pipeline type that triggered the original search.

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.

Turnaround time measures the gap between the first search timestamp and the confirmed import. It is displayed in human-readable form in the Imports tab.

If the same item is imported more than once (a quality upgrade after an initial grab), an iteration counter is incremented and shown as a x2 or x3 badge in the Imports tab.

The Sweep tab​

The Sweep tab shows a live view of the current or most recent sweep. The top row shows one pipeline card per active pipeline (Cutoff Unmet, Backlog, CF Score). Below that is a summary row with Sweep Health, Imports Confirmed, and Last Sweep. The bottom section is a paginated feed of items searched this sweep.

Pipeline cards​

Each pipeline card shows:

  • Last run timestamp -- top right corner, showing when this pipeline last ran. Blank if it has never run. Persists across restarts.
  • Aggregate totals row -- Searched, Cooldown, Capped, Excluded counts across all instances this run
  • Per instance rows -- the same stats broken down by instance, with a health dot per instance

The Cutoff Unmet card shows an "Always On" badge when the pipeline is enabled for both apps, or a per-app state if one app has it toggled off. Backlog and CF Score show Enabled or Disabled based on their global toggle.

When a pipeline is disabled for an instance, that instance row shows a Disabled label in place of stats.

Sweep Health card​

Shows the health banner (All Instances Healthy, Instance(s) Unreachable, or Sweep Failed) with a Stats section showing Lifetime Runs and Avg / Run. Lifetime Runs is the total number of sweeps completed since install. Avg / Run is the average number of items searched per sweep across all time.

Imports Confirmed card​

Shows the count of items confirmed imported since the last sweep ran. When imports exist, a Per Instance section shows Movies (Radarr) and Episodes (Sonarr) separately. When nothing was imported this sweep, a zero state is shown.

Last Sweep card​

Shows when the last sweep completed and when the next run is scheduled.

Searched This Sweep feed​

A paginated table of every item searched in the most recent sweep, with title, instance, time, and pipeline badge.

Cooldown and the History tab​

The History tab shows every search Nudgarr has triggered, most recent first. Each row includes the title, pipeline type, instance name, library added date, search count, and last searched timestamp.

You can sort by any column and filter by title or instance. The exclusion icon on any row adds the title to the Exclusions list. The Clear Exclusions button at the bottom of the tab lets you clear auto, manual, or all exclusions in bulk.

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.

Multiple instances​

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.