3rd Party Apps
Connect your *arr instances to Huntarr for automated media hunting, quality upgrades, and download management.
How App Connections Work
Huntarr communicates with each *arr application through its REST API. You provide the app's URL and API key, and Huntarr takes care of the rest — monitoring your library for missing media, identifying files that can be upgraded, and triggering searches automatically on a schedule you control.
- API-driven: Huntarr never modifies your *arr databases directly. It uses the same API endpoints the apps' own UI uses.
- Independent instances: Each connection is managed separately with its own hunt settings, cycle counts, and schedules.
- Multiple instances: You can add multiple instances of the same app (e.g., a 1080p Radarr and a 4K Radarr) and configure each independently.
- Non-destructive: Huntarr only triggers searches. Your *arr apps handle the actual downloading, importing, and file management.
Adding an Instance
- Navigate to the Apps section from the Huntarr sidebar.
- Select the app type you want to connect (Sonarr, Radarr, etc.).
- Click "Add Instance".
- Enter a friendly name (e.g., "Movies-4K" or "TV-Anime").
- Enter the full URL of your *arr instance, including the port (e.g.,
http://192.168.1.100:7878). - Paste the API key from your *arr app (found under Settings > General > Security in each app).
- Click "Test Connection" to verify Huntarr can reach the app.
- Save the instance.
Finding your API key: In any *arr app, go to Settings > General > Security. The API key is displayed there. Copy it and paste it into Huntarr.
Common Instance Settings
These settings are shared across all huntable apps (Sonarr, Radarr, Lidarr, Readarr, Whisparr):
| Setting | Default | Description |
|---|---|---|
| Name | — | A friendly label to identify this instance (e.g., "TV-1080p") |
| URL | — | Full URL including port (e.g., http://localhost:8989) |
| API Key | — | Found in the app under Settings > General > Security |
| Enabled | Yes | Toggle hunting on/off for this instance without deleting it |
| Hunt Missing | Enabled | Search for media that has no file on disk |
| Hunt Upgrades | Enabled | Search for better-quality versions of existing files |
| Missing Items per Cycle | 1 | How many missing items to search for each hunt cycle |
| Upgrade Items per Cycle | 1 | How many upgrades to attempt each cycle |
| Monitored Only | Enabled | Only hunt items you've marked as monitored in the *arr app |
Start low: Begin with 1–3 items per cycle to avoid overwhelming your indexers. You can increase later once you're confident everything is working well.
How Hunting Works
The hunt cycle follows the same pattern for all apps:
- Query: Huntarr calls the *arr app's API to get a list of missing or upgradeable items.
- Filter: Results are filtered by monitored status, availability, and your configured caps.
- Search: Huntarr sends a search command back to the *arr app for each selected item.
- Download: The *arr app handles the search results, selects the best release, and sends it to your download client.
- Repeat: After the configured interval, the cycle starts again.
Supported Apps at a Glance
| App | Media Type | Hunt Missing | Hunt Upgrades | Notes |
|---|---|---|---|---|
| Sonarr | TV Series | Yes | Yes | Episodes and seasons |
| Radarr | Movies | Yes | Yes | Includes Minimum Availability filtering |
| Lidarr | Music | Yes | Yes | Albums and tracks |
| Readarr | Books | Yes | Yes | eBooks and audiobooks |
| Whisparr | Adult | Yes | Yes | Supports v2 and v3 |
| Prowlarr | Indexers | — | — | Indexer management (no hunting) |
| Swaparr | Downloads | — | — | Stalled download management |
Sonarr
TV series — hunt missing episodes and upgrade quality.
- Sonarr manages TV series. Huntarr connects to it to find missing episodes and upgrade existing ones to better quality.
- Compatible with Sonarr v3 and v4.
- Ideal use case: you have a large TV library with hundreds of missing episodes that Sonarr's RSS feed will never find on its own.
- Multiple instances let you maintain separate libraries (e.g., 1080p anime vs 4K live-action).
Sonarr-Specific Behavior
- Huntarr searches at the episode level, not the series level. This means it can target individual missing episodes within a series.
- Upgrade hunts check each episode's current quality against the quality cutoff defined in your Sonarr quality profile.
- Huntarr skips unaired episodes and respects series monitoring settings.
Tips for Sonarr
- Start with 1–3 episodes per cycle to avoid indexer rate limits.
- If you have a large backlog (500+ missing episodes), consider increasing the cycle rate gradually over a few days.
- Check Sonarr's Activity > Queue if searches seem slow — downloads may be queued.
- Make sure Sonarr's indexers are healthy before enabling hunts.
Huntarr triggers searches through Sonarr — make sure Sonarr has working indexers and a download client configured before enabling hunts.
Radarr
Movies — hunt missing films and upgrade quality.
- Radarr manages movies. Huntarr connects to find missing films and upgrade quality.
- Compatible with Radarr v3+.
- Multiple instances supported (e.g., one for 1080p, one for 4K, one for kids' movies).
Radarr-Specific Settings
| Setting | Default | Description |
|---|---|---|
| Minimum Availability | Announced | When a movie becomes searchable: Announced, In Cinemas, or Released. Controls whether Huntarr will attempt to search for a movie based on its release status. |
Tips for Radarr
- Minimum Availability matters: Searching for "Announced" movies rarely finds results. Use "Released" for the best hit rate.
- Radarr's custom formats can help you target specific qualities and codecs.
- If movies aren't being found, verify that Radarr's Minimum Availability matches your expectations — a movie marked "Announced" likely has no releases yet.
- Multiple instances let you maintain separate quality libraries (e.g., a 1080p library and a 4K HDR library).
Lidarr
Music — hunt missing albums and upgrade audio quality.
- Lidarr manages music — albums, tracks, and artists.
- Compatible with Lidarr v1+.
- Multiple instances supported (e.g., FLAC lossless library vs MP3 portable library).
Lidarr-Specific Behavior
- Huntarr searches at the album level. Lidarr handles individual track matching.
- Album searches often return full discographies; Lidarr filters to the correct album automatically.
- Music indexers can be more inconsistent than video indexers — patience and multiple indexers help.
Tips for Lidarr
- Start with very low caps (1 album per cycle) since music indexers are often rate-limited.
- Use quality profiles in Lidarr to control FLAC vs MP3 preference.
- If missing albums aren't found, verify Lidarr has at least one healthy music indexer configured.
- Separate instances for FLAC and MP3 libraries is a common and recommended setup.
Readarr
Books — hunt missing eBooks and audiobooks automatically.
- Readarr manages books and audiobooks.
- Compatible with Readarr v0.1+.
- Multiple instances supported (e.g., one for eBooks, one for audiobooks).
Readarr-Specific Behavior
- Huntarr searches at the book level (individual titles).
- Audiobook searches may require specialized indexers that carry audio content.
- Book indexers can be limited compared to video — results may take longer to appear.
Tips for Readarr
- Separate instances for eBooks and audiobooks is strongly recommended since they use different indexers and quality profiles.
- Book indexers are niche — make sure you have at least one dedicated book indexer in your setup.
- Be patient with search results; book content is less widely available than TV or movies.
- Check Readarr's Activity queue for search progress.
Whisparr
Adult content — automated hunting and quality upgrades.
- Whisparr manages adult content.
- Compatible with Whisparr v2 and v3.
- Multiple instances supported.
Whisparr-Specific Behavior
- Huntarr uses the same hunt pattern as other *arr apps: query API, filter, trigger searches.
- Specialized indexers may be required for this content type.
- Quality profiles in Whisparr control resolution and format preferences.
Tips for Whisparr
- Whisparr v3 is recommended for the best API compatibility with Huntarr.
- If you're running v2, consider upgrading — v3 has better API support and stability.
- Use Huntarr's scheduling to keep indexer hit rates reasonable.
Version note: Huntarr supports both Whisparr v2 and v3. If you encounter API issues with v2, upgrading to v3 typically resolves them.
Prowlarr
Centralized indexer management for all your *arr apps.
Prowlarr is different from the other apps listed here. It does not hunt for media — instead, it manages the indexers that all your other *arr apps use for searching.
What Huntarr Does with Prowlarr
- Monitors indexer health and status from the Huntarr dashboard.
- Provides visibility into which indexers are online, offline, or rate-limited.
- Allows you to view Prowlarr configuration from within Huntarr's interface.
Prowlarr Settings
| Setting | Default | Description |
|---|---|---|
| URL | — | Your Prowlarr instance URL (e.g., http://localhost:9696) |
| API Key | — | Found in Prowlarr > Settings > General |
| Enabled | Yes | Monitor this Prowlarr instance |
Prowlarr doesn't have hunt capabilities. It manages indexers that Sonarr, Radarr, and other apps use. Keep Prowlarr healthy — it directly affects every other app's ability to find content.
Tips for Prowlarr
- Configure all your indexers in Prowlarr rather than in individual *arr apps — Prowlarr syncs them automatically.
- Huntarr will warn you if Prowlarr reports unhealthy or failing indexers.
- Regularly check indexer health to ensure your hunting is effective across all apps.
Swaparr
Automatically manage stalled and slow downloads.
Swaparr is a download management feature built into Huntarr. It monitors your download clients for stalled or slow downloads and automatically swaps them for better alternatives — reducing the need for manual queue management.
How Swaparr Works
- Swaparr monitors active downloads in your configured clients.
- Downloads that are stalled, extremely slow, or stuck receive a strike.
- After reaching the configured strike count, the problematic download is removed.
- A new search is triggered through the appropriate *arr app to find an alternative release.
- A new, hopefully better, download begins automatically.
Swaparr Settings
| Setting | Default | Description |
|---|---|---|
| Enabled | Yes | Enable Swaparr monitoring for this instance |
| Strike Count | 3 | Number of strikes before a download is swapped |
| Strike Interval | 5 minutes | Time between strike checks |
| Max Download Speed | — | Downloads below this speed (KB/s) receive strikes |
| Ignore Categories | — | Comma-separated download categories to exclude from monitoring |
Dashboard Stats
Huntarr displays Swaparr statistics on the home page:
- Total swaps performed
- Active strikes on current downloads
- Number of downloads being monitored
- Overall success rate
Tips for Swaparr
- Set the strike count to 3 or higher to avoid swapping downloads that are only temporarily slow.
- Use ignore categories for large downloads that are expected to be slow (e.g., 4K remuxes).
- Monitor the Swaparr stats on the dashboard to see if your settings need tuning.
- Works best with torrent clients (qBittorrent, Deluge, Transmission).
Swaparr removes and re-searches downloads. Make sure your *arr apps have good indexer coverage so alternative downloads can be found when a swap occurs.
General Tips
- Test connections first: Always test your connection before saving an instance. If the test fails, Huntarr can't hunt.
- Start conservative: Begin with 1 item per cycle for each app. You can always increase later.
- Check your indexers: Huntarr is only as good as the indexers configured in your *arr apps. No indexers = no results.
- Use scheduling wisely: Stagger your hunt cycles across apps to spread out indexer load.
- Multiple instances: Don't be afraid to use multiple instances of the same app for different quality levels or content categories.
- Monitor the dashboard: Huntarr's home page shows real-time hunt status, connection health, and activity across all your instances.