ARR Missing Searchers

Containerized workers for Sonarr, Radarr, and Lidarr.

Current scripts in this repo:

• sonarr_missing_searcher.py: searches Sonarr series (monitored, no rss tag) per series
• radarr_missing_searcher.py: searches Radarr movies (monitored, no rss tag) per movie
• lidarr_missing_searcher.py: searches Lidarr artists (monitored, no rss tag) per artist

The Sonarr worker:

1. Calls Sonarr GET /api/v3/series
2. Filters to monitored shows without the excluded tag (default rss)
3. Triggers POST /api/v3/command with SeriesSearch for each selected show

This is useful for periodic search passes while keeping the logic outside Sonarr.

How it works

• Loads the library from Sonarr/Radarr/Lidarr API endpoints (/series, /movie, /artist)
• Filters to monitored items without excluded tags (default rss)
• Ranks eligible items by release date (newest first, best effort)
• Targets the newest 1000 eligible items per run by default (TARGET_MISSING_RECORDS)
• If fewer than the target exist, it uses all eligible items
• Deduplicates records into unique ARR entity IDs before queuing searches
• Skips items whose series has an excluded Sonarr tag (default: rss)
• After a successful SeriesSearch queue, tags that series with rss so future runs skip it
• Processes series from newest release to oldest release (series.firstAired, fallback year)
• Sends a SeriesSearch command per series
• Sleeps between series searches to avoid hammering Sonarr/indexers
• Repeats on a configurable interval (or runs once and exits)

Environment Variables

• SONARR_URL (required): Sonarr base URL, e.g. http://sonarr:8989 or http://host:8989/sonarr
• SONARR_API_KEY (required): Sonarr API key
• SONARR_API_VERSION (default: v3)
• EXCLUDED_TAGS (default: rss) comma-separated Sonarr tag labels to skip, e.g. rss,manual-only
• PROCESSED_TAG_LABEL (default: rss) Sonarr tag label to add after a series is processed; keep this tag in EXCLUDED_TAGS so future runs skip it
• TARGET_MISSING_RECORDS (default: 1000) newest eligible untagged monitored items to process per run after exclusions (name retained for backward compatibility)
• CHECK_INTERVAL_SECONDS (default: 21600) how often to run (6h)
• SEARCH_DELAY_SECONDS (default: 2) delay between SeriesSearch commands
• SERIES_SEARCH_COOLDOWN_MINUTES (default: 720) avoid re-searching the same show too often while the container stays up
• PAGE_SIZE (default: 1000) legacy setting retained for compatibility (not used in current library-scan mode)
• MAX_SERIES_PER_RUN (default: 0) 0 means unlimited
• REQUEST_TIMEOUT_SECONDS (default: 30)
• RUN_ONCE (default: false) run a single cycle and exit
• DRY_RUN (default: false) log what would be searched without calling Sonarr
• LOG_LEVEL (default: INFO)

Docker Compose (Single Container, All Three Workers)

1. Edit .env and set the three URLs and API keys:
   • SONARR_URL / SONARR_API_KEY
   • RADARR_URL / RADARR_API_KEY
   • LIDARR_URL / LIDARR_API_KEY
2. Start all three workers:

docker compose up -d --build

This starts:

• one container: arr-missing-searchers
• inside it, a small supervisor starts sonarr, radarr, and lidarr workers

Docker Run (Single Container)

docker build -t arr-missing-searchers -f Dockerfile.all .
docker run -d --name arr-missing-searchers \
  --env-file .env \
  arr-missing-searchers

One-shot mode (for cron/Kubernetes jobs)

docker run --rm \
  --env-file .env \
  -e RUN_ONCE=true \
  arr-missing-searchers

Notes

• The workers scan the Sonarr/Radarr/Lidarr libraries and only process monitored items that do not have the excluded tag(s).
• Before searching, it resolves Sonarr tag IDs and excludes series tagged with EXCLUDED_TAGS (default rss).
• After queuing a SeriesSearch, it adds PROCESSED_TAG_LABEL (default rss) to the series via Sonarr so the series is skipped in future runs.
• It ranks eligible untagged monitored items by release date and processes the newest TARGET_MISSING_RECORDS.
• It sorts queued series by newest release first, then works toward older series.
• It triggers SeriesSearch per show (not per episode).
• Aggressive searching can hit indexer rate limits; tune CHECK_INTERVAL_SECONDS, SEARCH_DELAY_SECONDS, and MAX_SERIES_PER_RUN.

Radarr Worker (Movies)

Files:

• radarr_missing_searcher.py
• Dockerfile.all (shared single-container image)

What changes vs Sonarr:

• Uses RADARR_URL, RADARR_API_KEY, RADARR_API_VERSION (default v3)
• Searches per movie using Radarr MoviesSearch
• Tags processed movies with PROCESSED_TAG_LABEL (default rss) and excludes EXCLUDED_TAGS
• Sorts movies newest-to-oldest by release date (physicalRelease/digitalRelease/inCinemas, fallback year)
• Uses MAX_MOVIES_PER_RUN and MOVIE_SEARCH_COOLDOWN_MINUTES

Radarr uses the shared .env file (see .env.example). Relevant keys:

RADARR_URL=http://radarr:7878
RADARR_API_KEY=replace-me
RADARR_API_VERSION=v3
EXCLUDED_TAGS=rss
PROCESSED_TAG_LABEL=rss
TARGET_MISSING_RECORDS=1000
PAGE_SIZE=1000
MAX_MOVIES_PER_RUN=0
MOVIE_SEARCH_COOLDOWN_MINUTES=720
CHECK_INTERVAL_SECONDS=21600
SEARCH_DELAY_SECONDS=2
RUN_ONCE=false
DRY_RUN=false
LOG_LEVEL=INFO

Lidarr Worker (Artists)

Files:

• lidarr_missing_searcher.py
• Dockerfile.all (shared single-container image)

What changes vs Sonarr:

• Uses LIDARR_URL, LIDARR_API_KEY, LIDARR_API_VERSION (default v1)
• Scans monitored artists without excluded tags and searches per artist
• Searches per artist using Lidarr ArtistSearch
• Tags processed artists with PROCESSED_TAG_LABEL (default rss) and excludes EXCLUDED_TAGS
• Sorts artists newest-to-oldest by best available release date metadata (fallback year)
• Uses MAX_ARTISTS_PER_RUN and ARTIST_SEARCH_COOLDOWN_MINUTES

Lidarr uses the shared .env file (see .env.example). Relevant keys:

LIDARR_URL=http://lidarr:8686
LIDARR_API_KEY=replace-me
LIDARR_API_VERSION=v1
EXCLUDED_TAGS=rss
PROCESSED_TAG_LABEL=rss
TARGET_MISSING_RECORDS=1000
PAGE_SIZE=1000
MAX_ARTISTS_PER_RUN=0
ARTIST_SEARCH_COOLDOWN_MINUTES=720
CHECK_INTERVAL_SECONDS=21600
SEARCH_DELAY_SECONDS=2
RUN_ONCE=false
DRY_RUN=false
LOG_LEVEL=INFO