> For the complete documentation index, see [llms.txt](https://docs.uxwizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uxwizz.com/installation/optimization-tips/auto-delete-old-data-cron-jobs.md).

# Auto-delete old data (cron jobs)

Use **Settings → Scheduled Tasks** to choose how long UXWizz keeps recordings, heatmaps, and sessions. The dashboard stores the schedule; a server task runner must execute it.

Most storage growth comes from [full recordings](/api/session-recording.md) and heatmap data. You can remove old replay data while keeping session statistics longer.

## Choose a retention policy

1. Back up the database and check that the backup can be restored.
2. Open **Settings → Scheduled Tasks**.
3. Configure **Cleanup old recordings** and **Cleanup old heatmaps** with the retention period you need.
4. Enable **Delete old sessions** only if you also want to remove older session history. This changes historical reports.
5. Review the schedule and retention values, then save the task. Cleanup applies across the main database and configured Agency databases; the dashboard's selected domain is not a cleanup boundary.
6. Check task history after the next scheduled run. Investigate failures before repeatedly running cleanup manually.

{% hint style="warning" %}
Deleted data cannot be recovered from UXWizz. Restore it from a backup if needed. A zero-second session is not proof of a bot; do not enable **Cleanup zero-second sessions** just because some recordings have no playback data.
{% endhint %}

### How to run the cron jobs

| Installation                    | Runner setup                                                            |
| ------------------------------- | ----------------------------------------------------------------------- |
| Current Linux `install.sh`      | Installs systemd timers for the five-minute and hourly groups.          |
| Current Docker standalone image | Runs a scheduler inside the container after browser setup.              |
| Docker Compose                  | Uses the separate `scheduler` service.                                  |
| WordPress                       | Registers WP-Cron events; execution depends on WordPress cron activity. |
| Manual hosting setup            | Requires two cron jobs or equivalent scheduled tasks on the server.     |

In **Settings → Scheduled Tasks**, open **How to enable / check runners** (or **Check runners** in WordPress) and check both groups. Do not add duplicate cron jobs when timers or a Docker scheduler already run them.

For a manual Linux installation with file-based database settings, your administrator can add these entries to the **PHP service user's crontab**. Replace `/var/www/html` with the real application path. PHP CLI must meet the [requirements](/installation/requirements.md), and that user must be able to write `server/cron/log.txt`.

```cron
*/5 * * * * /bin/bash /var/www/html/server/cron/ust_run_scheduled_tasks.sh five_minute
0 * * * * /bin/bash /var/www/html/server/cron/ust_run_scheduled_tasks.sh hourly
```

If the application uses environment-based credentials, configure the runner to receive the same protected environment as PHP. Do not paste database passwords into cron entries. See [Environment settings](/guides/environment-settings.md).

### Troubleshooting

* **No recent runner activity:** check the systemd timers, container, hosting-panel job, or WP-Cron setup. This needs server or WordPress administration access.
* **Database connection error only in tasks:** the CLI process may have different environment settings from web PHP.
* **Permission denied:** check ownership of the named application path and log file. Do not make the application world-writable.
* **Execution disabled:** the administrator may have set `UXWIZZ_DISABLE_SCHEDULED_TASKS_EXECUTION=1`.
* **Task runs but removes little data:** check its retention period and run limits. Large cleanup jobs can need multiple runs.

### Built-in example scripts

Older installations include individual `ust_del_*.sh` scripts. Current installations should use Scheduled Tasks and the two runners above, so task history and settings stay together.

For an older installation that still uses those scripts, the original cron setup remains available. First verify that the named script exists in **your installed version**, inspect its retention value, and back up the database. These older scripts operate on the configured main database; they are not an Agency multi-database cleanup solution.

Example: to run the installed 60-day heatmap cleanup at 03:00 daily, add this to the PHP service user's `crontab -e`:

```cron
0 3 * * * cd /var/www/html/server/cron && /bin/bash ./ust_del_heatmap_60_days.sh
```

Use the actual application path. Calling Bash explicitly avoids needing executable permission on the `.sh` file; the service user still needs to read the scripts, connect to the database, and write `server/cron/log.txt`.

| Legacy script                | Purpose                                                                 |
| ---------------------------- | ----------------------------------------------------------------------- |
| `ust_del_heatmap_60_days.sh` | Remove heatmap data older than its configured cutoff.                   |
| `ust_del_record_60_days.sh`  | Remove old replay data in the formats handled by that installed script. |
| `ust_del_visitors_1_year.sh` | Remove old sessions and their related data.                             |
| `ust_limit_record_number.sh` | Apply the configured session limit.                                     |
| `ust_del_zero_sec_rec.sh`    | Remove zero-second sessions; these are not necessarily bots.            |

To use a different retention period, copy the relevant script to a new name and edit its interval. Test it on a restored database first. Some legacy scripts assume page IDs follow date order, which may not hold after a data import. Do not schedule both a legacy cleanup and the equivalent Scheduled Task. Remove the old crontab entry when you switch to the current runner.

Do not copy old cleanup commands into a new installation without checking its schema and database layout. In an Agency multi-database setup, back up the main database and every configured analytics database.

For backups or a server move, follow [Migrating to a new server](/guides/migrating-to-a-new-server.md). A retention task is not a backup.