Setting up a Matomo cronjob: archiving reports automatically

Setup

Step by step

1. Create a token for authentication

   Sign in as superuser and open Administration → Personal → Security. Under "Auth tokens" click "Create new token". Tick "Secure use only": the token is then only valid via POST, not as a parameter in the address. Matomo shows the token only once. Store it right away.

2. Disable browser archiving

   Under Administration → System → General settings set "Archive reports when viewed from the browser" to No and "Archive reports at most every X seconds" to 3600. Without this step Matomo keeps computing on every request.

3. Create an account at Cronjob.de

   Registration takes a minute and is free. Five cronjobs stay free forever, the first 14 days run on the Unlimited plan.

   Start for free 14 days of Unlimited included, no payment details

4. Create the cronjob: method POST, token in the body

   Choose POST as the method and enter https://your-domain.com/matomo/misc/cron/archive.php as the address. Use application/x-www-form-urlencoded as the content type and put token_auth= followed by your token into the request body. Matomo recommends POST for security reasons. Enter the final https address: a redirect turns POST back into GET, and the body is lost. A fixed minute of every hour is enough as a schedule.

   token_auth=YOUR32CHARACTERTOKEN
   
   # schedule, hourly at :17
   17 * * * *

5. Switch on error notifications

   Enter an email address under Notifications. When archiving fails, your reports go stale silently. Without a notification you often notice weeks later. Failure notifications by email are included from the Plus plan, and free during the first 14 days.

What the five fields of an expression like */5 * * * * mean is explained in the crontab reference – with examples and the most common pitfalls. You can build the expression in the crontab generator. Whether you need an outside service at all is shown in the comparison of the three ways.

Verification

Is it actually running?

In Matomo open Administration → Diagnostic → System Check. "Last Successful Archiving Completion" shows when archiving last finished. An old timestamp there means the call is not arriving. From Plus, the Cronjob.de call log also shows the response: the archiver output ends with "Done archiving!" and a summary.

FAQ

Common questions about Matomo

How often should the Matomo cronjob run?

At least once an hour, as the Matomo guide on auto-archiving says. Calling more often only helps if you also lower the "at most every X seconds" value. Otherwise Matomo still recomputes the reports only once an hour, and the extra calls just add load.

Archiving takes longer than a minute. Does it get cut off?

Our call ends after 45 seconds (free) or 60 seconds (Plus and Unlimited). Whether Matomo keeps running on your server after that depends on PHP: with ignore_user_abort = On in php.ini the script continues until your server's time limit applies. For large installations Matomo recommends the command line.

Why should the Matomo token be sent by POST instead of in the address?

Matomo recommends POST for security reasons. An address shows up in access logs and error messages, a body does not. If you created the token as "Secure use only", Matomo only accepts it via POST anyway.

I get "token_auth is invalid" or error 401.

Then the token does not belong to a superuser, it was deleted, or it has expired. Matomo can create tokens with an expiry date; after that date Matomo rejects them and sends a reminder by email beforehand. Create a new token under Administration → Personal → Security. Make sure no space is copied along with it.

Do I need an extra call for the scheduled tasks?

Usually not. After archiving, archive.php also runs the scheduled tasks, such as sending scheduled email reports. The API method CoreAdminHome.runScheduledTasks only triggers the scheduled tasks, without archiving.

I run Matomo for several websites. Does that change anything?

No, archive.php works through all websites of your installation one after another. The run may take longer than the window of a single call as a result. See the question about run time.