GA4 Annotations: Writing Down What the Chart Cannot Tell You

A client emails in March about a 34 percent drop in sessions during the second week of February. The chart shows the drop cleanly. What it does not show is that the site shipped a new product template on the Tuesday and the consent banner changed its wording on the Wednesday, because nobody wrote either of those things down.

The data survived. The reason did not. GA4 stores events, not context, and no amount of clicking around the interface will recover a fact that was never recorded. An annotation is the smallest fix for that problem, and it takes about fifteen seconds to add.

A chart records the drop, not the cause

Analytics tools keep an excellent record of what happened and a poor record of why. The why usually lives somewhere else. A deploy log, a Jira ticket, a campaign brief, a supplier email, a message in a channel that got archived when the team changed. Those places are searchable for a few months and then they are not.

This matters more for an agency than for an in-house team. An in-house analyst who lived through the February release still remembers it in June. An agency account changes hands, a client asks a new starter to explain last year's numbers, and the context is gone. The chart is what is left.

There is a quieter cost too. When a number moves and nobody can explain it, the call turns into a defence of the tracking instead of a discussion of the business.

What an annotation actually is

An annotation is a note attached to a date or a date range on a property. Google's help page describes the purpose plainly: to record events, explain changes in data, or flag observations for yourself and your team.

You create one from inside a report. Open Reports, right click any data point on a line graph, and choose Add annotation. You get a title, a description, a single date or a range, and a colour.

Once saved, the annotation appears across every report and report card that carries a line graph, not only the one you were looking at. An icon shows under the graph, a hover reveals the details, and clicking the icon opens the Annotations Viewer panel.

For a full view of a property, go to Admin, then Data display, then Annotations. That list shows every annotation on the property, and depending on your access level you can create, edit, delete or export them from there.

The one setting people miss sits at the bottom left of the Annotations Viewer, in a section called Annotations Settings. It holds a toggle that hides or unhides all annotations and annotation bars for date ranges, and the change applies to every annotation on the property. Useful for a dense month, and worth knowing before someone concludes the annotations were deleted.

The limits decide whether you keep using it

Three limits shape how the feature gets used in practice, and all three are worth knowing before you build a habit around it.

The first is length. A title can hold 60 characters and a description 150. That is short. It rules out pasting in a release note, and it is the reason the note has to be written for a stranger rather than for yourself.

The second is volume. Each property can hold 1000 annotations. That sounds generous until an agency with a chatty deploy pipeline starts annotating every release, so decide what earns a note.

The third is permission. You need Analyst or above at property level to create, edit or delete an annotation, and Viewer or above to see one. A junior on a client account may be able to read the history but not add to it, which is a staffing detail worth checking before you promise a client that everything gets logged.

Google also offers a practical warning in the documentation. If you expect a high number of annotations with overlapping date ranges, use a single date rather than a range. Overlapping ranges stack into bars nobody can read.

Change history covers the inside, annotations cover the outside

GA4 has a second record that people confuse with annotations, and the difference between them is the whole argument for using both.

Change history sits under Admin, either as Account change history or Property change history. It records changes made to the account or property over the last two years by default, and you can move the date range with a Time filter. It lists the time, the location type and name, the item type, the action taken, and who did it. It also captures some automated system changes, labels automatic property creation as System (Migration), and shows [deleted user] where the Google account behind a change no longer exists. The information icon on a row opens further detail, including before and after states, displayed as the Admin API representation of the object.

Reading that list makes the split obvious. Change history knows about things that happened inside GA4. A data filter switched to Active, a key event added, a Google Ads link created, a retention setting changed. It has no idea that the site deployed a new checkout, the CMP pushed a new banner version, or the client ran a radio ad on the Friday.

So the rule is simple. If the change was made in the GA4 interface, change history has it. If it was made anywhere else, the annotation is the only place it can exist. Most of the numbers that move are in the second group.

Google writes annotations too

Some of the notes on your charts are not yours. When a significant data-impacting event occurs, Google Analytics may add an annotation to the affected date and data. Those look like normal annotations with one difference: they cannot be edited or deleted.

The Admin API confirms the design. The annotation resource carries a systemGenerated field marked output only, and where that flag is true the annotation was created by Google Analytics and cannot be updated or deleted. The colour list backs it up further. Orange is reserved for system-generated annotations, so an orange note is a Google note.

That is worth knowing before you start debugging. If a client's traffic drops and there is an unremovable orange marker on the same day, read it first. It is cheaper than a tag audit.

Doing it at scale through the Admin API

Annotations can be created in the Reports interface or through the Admin API, which is the part that makes them usable as process rather than as good intentions.

The resource is properties.reportingDataAnnotations in the Admin API v1alpha. Each annotation carries a name in the form properties/{property_id}/reportingDataAnnotations/{annotation_id}, a required title, an optional description, a required colour, and either a single annotationDate or an annotationDateRange. The range is inclusive at both ends, the end date must be on or after the start date, and time zones follow the parent property. The available colours are purple, brown, blue, green, red, cyan and orange, with orange restricted to system annotations. The methods are create, delete, get, list and patch.

The obvious automations follow from having create and list. A deployment pipeline can write one when it ships to production, a release calendar when a campaign starts, a ticket close when a CMP version changes. A monthly audit can call list to find days that moved with no note against them.

Two cautions. The interface caps the title at 60 characters and the description at 150, so budget automation to the same size and test what happens when a generated title runs long. And this is an alpha endpoint, which means the surface can change without the usual stability promises. Keep the script small and easy to repoint.

A colour scheme that survives a staff change

Annotations become useful in proportion to how consistently they are written. A colour scheme does most of that work, because a colour reads before a title does.

One arrangement that holds up: red for anything that changes tracking itself, so tag manager releases, data filter changes, stream edits. Blue for site and CMS releases. Green for campaign and paid media launches. Purple for pricing, product and packaging changes that alter what people buy. Cyan for consent and CMP changes. Brown for infrastructure, so migrations, DNS moves, CDN changes and server-side deployments.

The title carries the what. The description carries the who and the reference, so a ticket number or a release name. One sentence is enough and the character limit enforces brevity whether you want it or not.

Then make it a ritual rather than a report. Before a monthly report goes out, put the chart next to the release calendar and cover any movement that has no note. That review takes ten minutes and it is the difference between a report that explains the month and a report that describes it.

Finally, export. Admin, Data display, Annotations gives you the list with export available at sufficient access, and the export is what leaves with the account when a client moves on. A record that only exists inside a tool the client is leaving is not a record.

The consent case, which is where most UK surprises live

Consent changes move numbers and leave almost no trace in the interface. A banner gains a second layer of choices. A CMP updates its default state. Someone flips ad_storage to denied in the default snippet while debugging and forgets to revert it. Each of those changes shows up as a shift in reported sessions, conversions or channel mix, and none of them appears in change history because none of them happened inside GA4.

The UK regulatory frame makes the note worth writing. The ICO's guidance on storage and access technologies, finalised in April 2026, keeps the position that nothing non-essential runs before consent, and that analytics or advertising storage needs a lawful basis rather than an assumption. A change to how consent is collected is therefore a change to what the data means, which is precisely the sort of thing the next person reading the chart needs to know.

Keep the two separate. An annotation records when something changed. It is not evidence of compliance, and a chart full of tidy notes proves nothing to a regulator. What it does show is that the team knew what it was doing and when.

What to do this week

1. Open the last three reports you sent and find the biggest move you still cannot explain.
2. Annotate the ones you can still date, using a single date rather than a range.
3. Write the colour scheme into the account notes so the next analyst inherits the convention rather than inventing one.
4. Check Admin, Data display, Annotations for the current count and the last entry, which tells you whether anyone is actually using it.
5. Add an annotation step to the deploy checklist, with the ticket number in the description.
6. Put a two-minute calendar review into the monthly reporting cycle, before the report is written.

None of this is difficult work. It is the cheapest form of documentation available in Google Analytics, and it is the only one that sits directly on the chart where the question gets asked. The interface will remember the number. Whether it remembers the reason is a decision someone has to make on the day.