Add and manage annotations

What appears in Events

The Events timeline combines manual notes with Google updates and opportunity milestones. When Annotations are enabled above a chart, events inside the active date range appear as markers. Select Events to review the full timeline.

Note

A manual event created by you, such as a content update, migration, campaign, technical change, or experiment.

Google update

A system-provided Google update marker that helps line up known updates with your data.

Opportunity

A milestone associated with the opportunity workflow.

Add a note

1. 1

   Open Events

   From a Search performance or GA4 chart, select Events.
2. 2

   Select Add note

   The timeline switches to a short event form.
3. 3

   Enter a clear title

   Use the thing that changed, such as “Rewrote pricing page title” rather than “SEO update”.
4. 4

   Choose the date

   Add an optional end date for migrations, campaigns, or experiments that span several days.
5. 5

   Choose a category and add details

   Explain why the change was made and what pages or assumptions were involved.
6. 6

   Save

   The note appears in the timeline and on charts whose date range includes it.

Edit, archive, restore, or hide annotations

• An account owner or member with write access can select Edit beside a manual note to change its title, dates, category, or details.
• Select Archive and confirm to remove a manual note from the active timeline and chart markers. Archiving is reversible.
• Select Archived notes in Events to review archived manual notes and restore one to the active timeline.
• Permanent deletion is available only from Archived notes. It requires a separate confirmation, checks the note’s current version, and cannot be undone.
• Google updates, opportunity milestones, and imported system events remain read-only and cannot be archived or deleted.
• Turn Annotations off above the chart to hide markers without changing any events.
• Changing the chart date range changes which markers are visible, but the full event remains saved.

Manage manual notes with an approved MCP client

A paid MCP connection can separately request the Manage annotations permission during consent. Its OAuth scope name is annotations:write. Existing connections do not gain it automatically; reconnect the client and explicitly approve the permission.

1. 1

   Ask the client to plan the change

   The client can propose create, update, archive, or restore for a manual note. Planning alone changes nothing.
2. 2

   Open the approval link

   The proposal expires after 15 minutes. Sign in as the same user who authorized the MCP connection.
3. 3

   Review the exact values

   CrawlRaven shows the action, site, note fields, and version before you approve or deny it.
4. 4

   Approve or deny

   Approval applies the exact plan once. The client can check status without repeating the mutation.

• Update, archive, and restore are version-checked. If someone changed the note first, the stale proposal conflicts instead of overwriting newer work.
• Create retries use an idempotency key so the same request does not create duplicate notes within the documented 90-day retention window.
• MCP can list archived notes and propose a restore, but it can never permanently delete a note.
• Only manual notes are mutable. Derived and imported events remain immutable regardless of the client’s scopes.

Use events to explain a change

1. Open an unfiltered 90-day Search performance view and locate the date movement began.
2. Open Events and check for a note, Google update, or opportunity milestone near that date.
3. Add a Page filter for the URL affected by the event.
4. Compare the page’s Queries before deciding that the event caused the movement.
5. If GA4 is linked, check sessions and key events for the same page and period.