Home FAQ Reporting Can we create an annotation in the future?

Can we create an annotation in the future?

Creating future-dated annotations in Matomo requires API intervention, as the standard web interface restricts annotation creation to current and historical dates to maintain data integrity and prevent accidental future data pollution. This limitation exists because annotations should typically document events that have already occurred and affected your analytics data.

The Matomo API provides the flexibility to create annotations for any date, including future dates, through the Annotations.add endpoint. Execute API calls using the following structure: https://your-matomo-domain/index.php?module=API&method=Annotations.add&idSite=1&date=2024-12-31¬e=Planned website redesign launch&starred=1&token_auth=your_token. Replace the parameters with your specific values, ensuring the date format follows YYYY-MM-DD conventions.

Future annotations serve valuable purposes in enterprise analytics environments. You can document planned marketing campaigns, website launches, promotional periods, or maintenance windows before they occur, creating comprehensive event tracking that facilitates post-event analysis. When these future events materialize, your annotations provide immediate context for any observed data changes.

To modify existing annotations, including those created for future dates, use the Annotations.save endpoint with the annotation’s idNote parameter. This allows you to update annotation text, star status, or other properties as circumstances change. For example, if a planned campaign shifts dates, update the annotation accordingly to maintain accuracy.

Implementation requires proper authentication through token_auth parameters, which should be generated with appropriate permissions for annotation management. Super Users can create annotations for any website, while regular users need specific access permissions for target websites.

Best Practice Warning: Future annotations can create confusion if used improperly, as team members may mistake planned events for historical occurrences. Establish clear naming conventions such as prefixing future annotations with “PLANNED:” or “SCHEDULED:” to distinguish them from historical events. Review and update future annotations regularly, converting them to standard historical annotations once events occur.

Consider integrating future annotation creation into your campaign planning workflows, automatically generating annotations through API calls when marketing campaigns or technical deployments are scheduled, ensuring comprehensive documentation of all planned activities that might influence your analytics data.