How to Configure Download Interval and Avoid Apple API Throttling with docker-icloudpd

Set download_interval to at least 43200 seconds (12 hours) in your environment configuration to prevent Apple API throttling, or enable single_pass=true for external scheduling control.

The docker-icloudpd container automates iCloud Photos downloads, but aggressive polling triggers Apple's rate limiting. Configuring the download_interval and understanding the throttling mechanisms implemented in the launcher scripts ensures reliable, uninterrupted backups according to the boredazfcuk/docker-icloudpd source code.

Understanding the Download Interval Settings

The container's behavior is controlled through three key variables parsed by launcher.sh and executed by sync-icloud.sh.

download_interval

The download_interval setting defines the sleep duration between download cycles in seconds. According to init_config.sh (lines 96-97), the default value is 86400 (24 hours). The launcher accepts specific values: 21600 (6h), 43200 (12h), 86400 (24h), 129600 (36h), 172800 (48h), or 604800 (7d).

download_delay

The download_delay parameter adds extra minutes to the interval before the next run begins. This value defaults to 0 and can be any integer, providing flexibility when staggering multiple container instances.

single_pass Mode

When single_pass is set to true, the container executes one download cycle and exits immediately, ignoring the download_interval value. As documented in CONFIGURATION.md (line 106), this mode requires the Docker restart policy to be set to no to prevent rapid restart loops that trigger throttling.

Configuring the Download Interval in docker-icloudpd

Using a .env File with Docker Compose

Create an .env file in your docker-compose directory:

# .env configuration

download_interval=43200
download_delay=0
single_pass=false

Reference it in your docker-compose.yml:

services:
  icloudpd:
    image: boredazfcuk/docker-icloudpd
    env_file: .env
    restart: unless-stopped

Runtime Environment Variables

Override settings at runtime for testing:

docker run -e download_interval=86400 -e download_delay=5 \
  boredazfcuk/docker-icloudpd

This runs a 24-hour interval with a 5-minute extra delay.

Single-Pass Mode with External Scheduling

For cron-based scheduling, enable single-pass mode:

# .env

single_pass=true
download_interval=86400  # Ignored when single_pass=true

Then schedule via host cron:

# Run daily at 3:00 AM

0 3 * * * docker run --rm --env-file /path/to/.env boredazfcuk/docker-icloudpd

Important: When single_pass=true the Docker restart policy must be no (default) to avoid an immediate relaunch after the run finishes.

Avoiding Apple API Throttling

The 12-Hour Safety Threshold

The launcher.sh script (lines 398-403) enforces a critical safety check: if download_interval is set below 43200 seconds (12 hours), the container prints a warning that short intervals may cause throttling by Apple. The script explicitly recommends switching the container off for 6-12 hours to allow Apple's throttling window to expire if rate limiting occurs.

Recovery from Throttling

If you encounter throttling:

1. Stop the container immediately
2. Wait 6-12 hours without API calls
3. Ensure download_interval is set to at least 43200 before restarting
4. Check logs with docker logs <container> to verify the warning has cleared

Summary

• Set download_interval to at least 43200 seconds (12 hours) to avoid Apple API throttling, or use single_pass=true with external scheduling.
• The download_delay parameter adds minutes to the interval for staggering multiple instances.
• launcher.sh enforces a 12-hour safety threshold and warns when shorter intervals risk rate limiting.
• Recovery from throttling requires stopping the container for 6-12 hours before resuming with compliant settings.

Frequently Asked Questions

What is the default download interval in docker-icloudpd?

The default download_interval is 86400 seconds (24 hours), as defined in init_config.sh (lines 96-97). This conservative default ensures new users avoid immediate throttling while maintaining regular daily backups.

How do I know if Apple is throttling my docker-icloudpd container?

When download_interval is set below 43200 seconds (12 hours), launcher.sh (lines 398-403) prints a warning message indicating that short intervals may cause throttling by Apple. If downloads suddenly fail or authenticate slowly after frequent restarts, stop the container for 6-12 hours to clear the throttle.

Can I run docker-icloudpd more frequently than every 12 hours?

While technically possible by setting download_interval to 21600 (6 hours), this triggers the safety warning in launcher.sh and risks Apple API throttling. To run more frequently without throttling, use single_pass=true mode with an external cron scheduler, ensuring the container fully stops between runs rather than looping internally.

Where does docker-icloudpd store the download interval configuration?

The configuration is stored in the container's internal configuration file generated by init_config.sh, but you override it via the download_interval environment variable passed through your .env file or docker run command. The launcher.sh and sync-icloud.sh scripts read this value to control the sleep cycle between downloads.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}