Chart notes

Chart notes add dated event markers to Semrush trend charts across tools such as Position Tracking and Domain Overview.

Finding and reading notesCopy Anchor Link

List notes with tool, date, or project filters:

semrush note-databases
semrush notes --tools '["POSITION_TRACKING"]' --project-ids '[456]' --page 1 --per-page 20
semrush notes --tools '["DOMAIN_OVERVIEW"]' --database us --include-hidden false
semrush note --note-id 'note-id-placeholder'

Pagination is 1-based. Date filters (--datetime-from and --datetime-to) accept UTC ISO timestamps (for example, 2026-10-15T00:00:00Z).

Creating and updating user notesCopy Anchor Link

Create a note attached to a specific SEO project or across all projects:

semrush note-create --title 'Redesign Launch' \
  --note 'Deployed new marketing site design' \
  --datetime 2026-10-15T00:00:00Z \
  --tools '["POSITION_TRACKING"]' \
  --project-id 456 \
  --confirm

Tool notes for Domain Overview and Organic Positions require at least one uppercase country code, such as --databases '["US"]'.

Modify an owned note while preserving omitted fields:

semrush note-update --note-id 'note-id-placeholder' --title 'Redesign Follow-up' --confirm
semrush note-update --note-id 'note-id-placeholder' --link '' --confirm
semrush note-delete --note-id 'note-id-placeholder' --confirm

Passing an empty string to --note or --link clears that content. Published system notes are protected and cannot be modified or deleted.

Controlling chart visibilityCopy Anchor Link

Hide or restore specific notes without altering their content:

semrush note-hide --note-id 'note-id-placeholder' --confirm
semrush note-show --note-id 'note-id-placeholder' --confirm

Manage hidden note categories for a chart context:

semrush note-hidden-categories --tool POSITION_TRACKING --project-id 456
semrush note-hidden-categories-set --tool POSITION_TRACKING --project-id 456 \
  --categories '["UNCONFIRMED"]' --confirm

Passing an empty array '[]' restores visibility for all note categories in that context.

Exporting notesCopy Anchor Link

Export all chart notes to CSV:

semrush notes-export --output notes.csv

The CLI verifies that notes.csv does not already exist before downloading.