How to Add Annotations to Charts in Amplitude

You’re staring at a spike in your Amplitude chart. Engagement jumped 40% on a specific date. But no one on the team can remember what happened that day.

Was it a feature release? A marketing push? A bug fix that finally shipped?

Without annotations, your data tells half the story. The context lives in someone’s memory — or worse, a forgotten Slack thread. That’s a problem when product decisions depend on understanding why numbers moved, not just that they moved.

Annotations solve this. They let you pin notes directly to your charts — marking the exact dates of launches, campaigns, experiments, and incidents. No more guessing. No more archaeology through old meeting notes.

Amplitude powers more than 45,000 digital products across over 1,000 enterprise customers, including 23 of the Fortune 100. In 2024 alone, the platform ingested nearly 19 trillion events. The teams getting the most value from that data aren’t just tracking events — they’re documenting the context around them.

This guide walks you through everything you need to know about adding, managing, and maximizing annotations in Amplitude charts.

What Are Annotations in Amplitude?

Annotations are time-stamped markers you attach to charts. They appear as vertical lines on your time series charts, with numbered markers displayed beneath the x-axis. Hover over any number and you see the annotation label and description you saved.

Think of them as sticky notes for your data. Every significant change — a new onboarding flow, a pricing update, a product launch, a paid campaign — gets logged directly onto the chart where its impact is visible.

The product analytics market is growing at a 14.83% CAGR and is projected to reach $22.74 billion by 2030, according to Mordor Intelligence. The companies extracting the most ROI from these tools are the ones building institutional knowledge into their analytics workflow. Annotations are one of the simplest ways to do that.

Why Annotations Matter for Your Analysis

Here’s the hard truth: raw data without context is unreliable.

When your retention curve dips in week two, three different people will offer three different explanations. One points to a backend deploy. Another mentions a marketing email that went out. A third thinks it was a holiday. Everyone is guessing.

Annotations eliminate that ambiguity. When every meaningful event is marked on the chart at the exact date it happened, the team interprets data from the same shared understanding. That matters because according to Forbes, data-driven businesses are 23 times more likely to acquire new customers, 19 times more likely to stay profitable, and seven times more likely to retain existing customers than competitors who aren’t operating this way.

Annotations are how you make your analytics genuinely data-driven — not just data-present.

Common use cases include:

• Feature launches and rollbacks
• Marketing campaign start and end dates
• A/B test deployments
• Infrastructure changes or outages
• Onboarding flow updates
• Pricing or packaging changes

Who Can Add Annotations in Amplitude?

Before you dive in, know the access requirement: only users with Admin or Manager permission levels can create annotations in Amplitude. If you don’t see the annotation option, your account likely has a lower permission level.

Check with your workspace admin to request the right access. Once you have it, annotations are straightforward to create.

Also worth noting: chart-specific annotations are only available for Event Segmentation and User Sessions charts. Global annotations apply across all time series charts in the project.

How to Add Annotations to Charts in Amplitude

Follow these steps to add your first annotation:

Step 1 — Open any time series chart

Navigate to your Amplitude workspace and open an Event Segmentation or User Sessions chart. Annotations are only supported on time series views, so make sure your chart is displaying data over a date range.

Step 2 — Locate the annotation trigger

Look for the + icon positioned to the right of the x-axis at the bottom of the chart. This is the annotation entry point. In some views, you may see it labeled as the “Add” icon in the Chart Editor’s bottom-right section.

Step 3 — Click the + icon

Clicking it launches a modal window where you’ll enter all the details for your annotation.

Step 4 — Fill in the annotation details

Inside the modal, complete the following fields:

• Affected Date — The specific date the event occurred
• Annotation Name — A short, clear label (e.g., “Checkout Flow Redesign” or “Email Campaign — March Cohort”)
• Description — A brief explanation of what happened and why it’s relevant
• Category — Assign the annotation to a category if you’ve set them up (covered below)

Step 5 — Set visibility

You’ll see a Visibility toggle that controls whether this annotation appears across all charts in the project or only on the specific chart you’re currently viewing. Toggle it on if you want global visibility; leave it off for a chart-specific annotation.

Step 6 — Save

Click Save. The annotation now appears as a vertical line on your chart at the marked date, with a numbered indicator below the x-axis.

That’s it. Your data point is now contextualized.

How to Add Date-Range Annotations

Not every event happens on a single day. A marketing campaign might run for two weeks. A degraded API might cause issues over a three-day window.

Amplitude supports date-range annotations that span multiple days. When creating or editing an annotation, you’ll see both a start date and an end date field. Fill in both to mark the full span of the event.

For example, if you ran a paid acquisition campaign from March 4 through March 8, enter those exact dates. The annotation will cover that entire range on the chart, making it easy to see the precise window during which your metrics were influenced.

A December 2025 quality-of-life update from Amplitude also improved the experience: hovering over an annotation in the popup now highlights the corresponding date line (or the full range, for range annotations) directly on the chart. That makes it much easier to interpret data when multiple annotations are clustered together.

Annotation Categories: Organize and Filter

If your team is active about marking events, your charts can get busy fast. Annotation categories are the answer.

Categories let you group annotations by type — for example, “Releases,” “Campaigns,” “Experiments,” or “Incidents.” Once grouped, you can show and hide entire categories from the chart view without deleting anything.

Here’s how to use them effectively:

• Create categories in your Project Settings under annotation management
• Assign categories when you create a new annotation using the Category dropdown in the modal
• Toggle visibility of categories directly on the chart, so you can isolate only the annotations relevant to your current analysis

When setting up a category, you can specify whether it displays by default on all charts within the project, or whether users need to manually enable it per chart. This gives teams fine-grained control over what context shows up where.

Amplitude’s December 2025 API update also added new REST endpoints specifically for managing annotation categories programmatically — useful for teams managing annotations at scale.

Chart-Specific vs. Global Annotations

This distinction matters more than it seems.

Global annotations are visible across every time series chart in the project. These are ideal for major events that affect the entire product — a significant backend migration, a product-wide redesign, a compliance-related change.

Chart-specific annotations are only visible on the chart where you created them. These are better for granular, context-specific notes — like a one-time segmentation test that only affects a particular funnel chart.

One important limitation to know: annotations do not support public links and are not accessible in dashboards or notebooks. If you’re sharing a chart externally or embedding it in a Notion document, the recipient won’t see your annotations. This is a current product constraint in Amplitude.

For teams who rely heavily on dashboards, the recommended workaround is to document annotation context in your dashboard description or in a linked source of truth.

Managing and Editing Annotations

Over time, annotations accumulate. Keeping them accurate matters — an outdated or mislabeled annotation is worse than no annotation at all because it actively misleads your analysis.

To manage your annotations:

• Navigate to Project Settings
• Select the Annotations section
• From here, you can view all existing annotations, edit labels and descriptions, update dates, reassign categories, or delete annotations that are no longer relevant

Deleting an annotation removes it from all charts across the project. There’s no partial removal — if it’s deleted from settings, it’s gone everywhere.

Using the Annotations API

For teams managing large volumes of annotations, doing it manually through the UI doesn’t scale. Amplitude’s Chart Annotations API (v3) lets you create, read, update, and delete annotations programmatically.

The API uses basic authentication with your API key and secret key. A standard POST request to create an annotation looks like this:

POST https://amplitude.com/api/3/annotations

Key fields you can pass in:

• label — The annotation name
• start — Start date and time (ISO 8601 format)
• end — End date and time (for date-range annotations)
• category — Annotation category name
• chart_id — Specific chart ID if you want a chart-specific annotation (null for global)
• details — Longer description of the event

This is especially useful for integrations. For example, a CI/CD pipeline can automatically post an annotation to Amplitude every time a deployment ships. No manual step required — the context is captured automatically at the moment of the event.

The API also supports GET requests to list annotations within a date range or by category, and PUT requests to update existing annotations. A December 2025 update extended the API to fully support category management and expose the new end date field.

Best Practices for Getting More Out of Annotations

Annotations only deliver value when teams use them consistently. Here’s what separates teams that get real insight from the feature versus teams that set it up and forget it:

Annotate in real time, not retrospectively. The best time to log a deployment or campaign is the moment it happens — not two weeks later when you’re trying to explain a trend. Build the habit of adding an annotation as part of your launch or campaign checklist.

Be specific with names. “Deploy” tells you almost nothing. “Checkout CTA Button — Color Test Deployed” tells you everything you need. The extra 15 seconds spent on a good label saves hours of future archaeology.

Use categories from day one. Even if you only have a few annotations at first, setting up categories early prevents the organizational headache of cleaning up an uncategorized backlog later.

Audit quarterly. Review your annotations in Project Settings every quarter. Remove outdated entries, update descriptions that no longer reflect what actually happened, and consolidate duplicate or overlapping annotations.

Use the API for automations. Any event that happens programmatically — deploys, experiment starts, integration syncs — should be annotated programmatically. Manual logging introduces gaps.

G2 has ranked Amplitude number one for product analytics four years running. The teams getting the most out of that ranking are the ones treating their analytics workspace like a living document — not just a place to pull numbers, but a shared record of why those numbers look the way they do.

Conclusion

Your charts are only as useful as the context behind them. Numbers without narrative create confusion. Annotations are the simplest, highest-leverage habit you can build into your Amplitude workflow — turning a static data view into a living record of your product’s history.

Start with the big events: launches, experiments, campaigns. Build the habit of annotating in real time. Set up categories before you need them. And if you’re managing annotations at scale, move to the API.

The teams winning on product analytics aren’t just collecting data. They’re building shared context that makes every decision faster and more defensible.

And once you know which moves are working in your product? The next step is putting that intelligence to work in your outbound pipeline. SalesSo helps you turn product and market insight into targeted outbound campaigns — cold email, cold LinkedIn, and cold calling — designed to reach the buyers most likely to convert. Book a strategy meeting to see how.