Scheduling

Control when and how often Huntarr hunts for missing and below-cutoff media across all your instances.

Overview

Scheduling is the heart of Huntarr. Each supported app type (Sonarr, Radarr, Lidarr, Readarr, Whisparr, and the built-in Movie Hunt) has its own independent schedule. You can configure:

• How often each app hunts (interval in minutes)
• How many items it searches per cycle (missing cap and upgrade cap)
• Per-instance or global schedules — run one schedule for all instances of an app, or fine-tune each instance separately

How a Hunt Cycle Works

Understanding what happens during each cycle helps you set good values:

1. Timer fires — When the configured interval elapses, Huntarr begins a hunt cycle for that app type
2. Library scan — Huntarr queries the app's API for all monitored items and identifies which are missing or below your quality cutoff
3. Queue check — Before triggering searches, Huntarr checks the app's download queue. If the queue already has active downloads, it may skip or reduce the batch to avoid overloading your download client
4. Batch search — Huntarr triggers searches for up to the configured cap of items. It picks items randomly or by priority (depending on app type) to spread searches across your library over time
5. Wait — The scheduler resets and waits for the next interval

Creating a Schedule

Navigate to Settings → Scheduling from the sidebar:

1. Select an App Type from the dropdown (Sonarr, Radarr, Lidarr, Readarr, Whisparr, or Movie Hunt)
2. Choose a specific instance or select Global to apply the schedule to all instances of that type
3. Set the Interval — how many minutes between each hunt cycle
4. Set the Missing Cap — maximum missing items to search per cycle
5. Set the Upgrade Cap — maximum items to search for quality upgrades per cycle
6. Toggle Enabled on or off
7. Click Save

Schedule Settings Reference

Setting	Description	Guidance
App Type	Which *arr app this schedule controls	One schedule per app type (or per instance)
Instance	Specific instance or "Global" for all	Use per-instance schedules to stagger load across 1080p and 4K instances
Interval	Minutes between hunt cycles	15–60 min recommended. Under 15 min risks indexer rate limits
Missing Cap	Max missing items to search per cycle	Start with 3–5. Higher values send more API calls to indexers per cycle
Upgrade Cap	Max items to search for quality upgrades per cycle	Start with 2–3. Upgrade searches are less urgent than missing-content searches
Enabled	Toggle this schedule on/off	Disable temporarily without deleting the schedule

Recommended Starting Settings

These defaults work well for most users. Adjust after observing your system for 24–48 hours:

App	Interval	Missing Cap	Upgrade Cap	Notes
Sonarr	30 min	5	3	Episode-level searches are fast. Safe to search more frequently
Radarr	60 min	3	2	Movies generate more indexer queries per search than episodes
Lidarr	60 min	3	2	Music indexers are often slower. Keep caps low to avoid timeouts
Readarr	120 min	2	1	Book indexers are limited. Very low caps recommended
Whisparr	60 min	3	2	Similar to Radarr in terms of search load
Movie Hunt	30 min	5	3	Uses Huntarr's own indexers (Index Master), so won't conflict with *arr indexer limits

Multiple Instances Strategy

If you run multiple instances of the same app (e.g., a 1080p Sonarr and a 4K Sonarr), stagger their schedules to avoid hammering your indexers simultaneously:

• Offset intervals — Set Instance A to 30 min and Instance B to 30 min, but they'll naturally offset because they start at different times
• Different caps — Give your primary (1080p) instance a higher missing cap (5) and your 4K instance a lower cap (2), since 4K content is harder to find anyway
• Use per-instance schedules — Avoid "Global" if your instances have different purposes or indexer configurations

Queue-Aware Pausing

Huntarr automatically checks your download client's queue before triggering searches. If your queue is already full or has many active downloads, Huntarr will:

• Reduce the batch size (search fewer items than the configured cap)
• Skip the cycle entirely if the queue exceeds the threshold
• Retry on the next scheduled interval

This prevents your download client from becoming overloaded and ensures existing downloads complete before new ones are added.

Monitoring Schedule Execution

Check if your schedules are working properly:

• Hunt Manager (System → Hunt Manager) — Shows the current status of each schedule, when it last ran, and what it found
• Logs (System → Logs) — Detailed log entries for each hunt cycle, including how many items were searched, found, and grabbed
• Dashboard — The home page shows per-app status cards with recent activity

Troubleshooting

Huntarr isn't finding anything

• Check that your *arr app has monitored content that is actually missing. Unmonitored items won't be searched
• Verify your indexers are working in the *arr app itself — try a manual search
• Check the Logs for errors like API timeouts or authentication failures

Getting rate-limited by indexers

• Increase your interval (try 60 minutes instead of 15)
• Decrease your caps (try 2 instead of 10)
• If you use the same indexers across multiple *arr apps, their combined search volume counts toward the indexer's rate limit

Schedules seem stuck

• Check the Hunt Manager — a schedule may be "waiting" because the download queue is full
• Restart the Huntarr container if schedules appear frozen
• Verify the app instance is still reachable (check the Apps page for connection status)