# How to Configure Download Interval and Avoid Apple API Throttling with docker-icloudpd > Learn how to configure download interval and avoid Apple API throttling with docker-icloudpd. Set download_interval to 12 hours or enable single_pass for external scheduling control. - Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd) - Tags: how-to-guide - Published: 2026-02-26 --- **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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) and executed by [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh). ### download_interval The **`download_interval`** setting defines the sleep duration between download cycles in seconds. According to [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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: ```text # .env configuration download_interval=43200 download_delay=0 single_pass=false ``` Reference it in your [`docker-compose.yml`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml): ```yaml services: icloudpd: image: boredazfcuk/docker-icloudpd env_file: .env restart: unless-stopped ``` ### Runtime Environment Variables Override settings at runtime for testing: ```bash 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: ```yaml # .env single_pass=true download_interval=86400 # Ignored when single_pass=true ``` Then schedule via host cron: ```bash # 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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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 ` 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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) and [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) scripts read this value to control the sleep cycle between downloads.