How to invalidate the past historical reports so they can be re-processed from the logs

Matomo stores reports as archived, aggregated data generated from log data. When you open reports for past periods, Matomo reads data from these archive tables instead of recalculating results from log data.

In certain situations, you will need to invalidate these archives and rebuild them from the underlying log data. This typically applies when:

• Sending backdated tracking requests using the HTTP Tracking API with the cdt parameter, which defines the date and time of the tracked action. If Matomo has already archived reports for that date, newly inserted log data will not appear in reports until the affected archives are rebuilt.
• Creating new Custom Reports or Funnels and you need archived data for past dates.
• Changing archiving-related configuration settings, such as reporting more than the default 500 rows.

This guide explains how to invalidate archived data using one of three methods: the InvalidateReports plugin, a console command, or the HTTP API. You can target one or more websites, a specific date range (or all dates), and a specific segment (or all segments).

Option 1: The InvalidateReports plugin

Use the free InvalidateReports plugin (by Matomo/InnoCraft) to invalidate your historical data directly within the user interface in just one click. If you need to invalidate historical data often, this may be the easiest solution.

1. In Matomo, go to Administration > Platform and search for the plugin.
2. Click Install to download and install the plugin files.
3. Enable the plugin by clicking Activate.
4. To use the feature, open System > Invalidate Reports in Administration settings.

Option 2: Use a console command

You can invalidate and rebuild archived reports using Matomo’s console commands.

• First, invalidate existing archives using core:invalidate-report-data and target multiple sites, a date range (–dates=2024-12-01,2024-12-31) or segment (--segment="browserCode==FF"). The following example marks the archives for those sites and date as invalid. It does not immediately rebuild them.

./console core:invalidate-report-data --dates=2025-01-01,2025-01-31 --sites=1,3,5

• Rebuild the archives by running core:archive. This processes the invalidated periods and regenerates the reports. If you use cron archiving, this step may already run automatically.

Reprocess only one specific report

Instead of reprocessing all reports, you can specify certain reports using the --force-reports option with core:archive. The following example forces Matomo to only rebuild the VisitsSummary report for the specified site and date.

./console core:archive \
  --idsite=1 \
  --force-date-range=2024-12-01,2024-12-01 \
  --force-reports=VisitsSummary

This is useful when a single report was affected by a configuration change and you want to reduce processing time. To specify multiple reports to reprocess at once, use commas to separate the report names:

--force-reports=Actions.getPageUrls,Actions.getPageTitles

When to use core:invalidate-report-data and core:archive

Invalidating archived data and rebuilding reports are separate operations in Matomo where a typical workflow runs:

1. core:invalidate-report-data to flag outdated archives, and
2. core:archive to rebuild the reports, or wait for the next scheduled archiving process.

core:invalidate-report-data

The core:invalidate-report-data command marks existing archived reports as invalid without reprocessing them. It flags specific websites, date ranges, or segments so that Matomo knows the archived data for those periods is outdated.

The actual rebuilding of reports happens during the next archive run, either via scheduled cron archiving or automatically when a user accesses the report (browser-triggered archiving). Use the command when you know archived data is outdated and must be regenerated later. This command is lightweight because it only marks archives as invalid.

core:archive

The core:archive command processes log data and builds or rebuilds archived reports immediately. Unlike core:invalidate-report-data, it performs the actual aggregation work at the time it is executed.

Depending on the number of websites, date ranges, segments, and reports being processed, this operation can be resource-intensive. You can limit the scope by targeting specific sites, dates, segments, or individual reports using options such as --force-reports.

Option 3: Use the HTTP API

You can invalidate archived reports using CoreAdminHome.invalidateArchivedReports. This API method only invalidates archives. To rebuild them immediately, run the core:archive command, otherwise, reports will be rebuilt during the next scheduled archiving process.

The following example invalidates daily reports for website ID 1 on 1 December 2024:

?module=API
&method=CoreAdminHome.invalidateArchivedReports
&idSites=1
&period=day
&dates=2024-12-01
&token_auth=YOURTOKEN

This marks the selected archives as invalid. It does not immediately rebuild reports, which are regenerated during the next archive run (cron or browser-triggered archiving).

Invalidate a specific segment (optional)

To invalidate reports for a specific segment only, add the segment parameter: &segment=pageUrl=@example.org/contact. This invalidates archived reports only for the matching segment.

Target a specific period type (optional)

You can restrict invalidation to a specific archive period (day, week, month, year, or range) using the period parameter, for example: &period=month.

This API method only invalidates archives. Your historical data will be reprocessed the next time auto archiving runs or you can manually run the archive command:

./console core:archive --force-all-websites --url=YOUR_MATOMO_URL_HERE

Specify a date range to archive after invalidating reports:

./console core:archive --force-all-websites --force-date-range=2025-01-01,2025-01-31 --url=YOUR_MATOMO_URL_HERE

For Matomo 3.x, run the following command:

./console core:archive --force-all-websites --force-all-periods=315576000 --force-date-last-n=1000 --url=YOUR_MATOMO_URL_HERE

Cascading invalidation behaviour

When you invalidate a lower-level period, such as a week, Matomo automatically invalidates all higher-level periods that include it, such as the corresponding month and year. This is known as cascading invalidation.

By default, invalidation only cascades upwards. For example, invalidating a month does not invalidate the days or weeks within that month. It will recalculate the monthly total, not each individual day.

To force invalidation of lower-level periods as well:

• In the CoreAdminHome.invalidateArchivedReports API, add &cascadeDown=1
• In the core:invalidate-report-data command, use the --cascade option

This ensures that both higher-level and lower-level periods are marked for reprocessing.