Chart annotations let you mark important events - deploys, releases, marketing campaigns, incidents, custom milestones - on every Zenovay timeseries chart. When traffic or revenue moves, you can see what changed near the same moment without leaving the dashboard.
Why annotations matter
Most analytics questions reduce to "what changed?" An unexplained drop on Tuesday afternoon is far easier to triage when you can see "deploy: release v2.5" marked at 14:32. Annotations turn the dashboard into a single timeline where business metrics and operational events live side by side.
The five annotation types
| Type | Color | Typical use |
|---|---|---|
deploy | Blue | Code deploys, infrastructure changes, configuration pushes |
release | Emerald | Public release announcements, version cuts |
campaign | Amber | Marketing campaigns, ad launches, email sends |
incident | Red | Customer-impacting incidents, outages |
custom | Violet | Anything else - board meetings, partner integrations, audits |
Each type has a distinct icon and color so you can scan the chip strip below a chart and spot the kind of change at a glance.
Three ways to create annotations
Option 1 - In the dashboard
Open your website's dashboard and select the Analytics tab, then click the note icon on any point of the visitor chart. The day-detail dialog opens with three tabs: Notes, Annotations, and Commits. On the Annotations tab, pick a type (deploy, release, campaign, incident, or custom), type a message, and add it. The marker appears on the chart right away.
This is the quickest way to mark a one-off event. For deploys you ship on a schedule, the CLI below is a better fit.
Option 2 - Zenovay CLI (recommended for CI)
The CLI is the canonical way to mark deploys from a CI pipeline. It
uses the same login as the rest of the CLI (zenovay login) and runs
on macOS, Linux, and Windows.
zenovay annotation create --type=deploy --message="release v2.5"
Add it as the last step of your deploy pipeline so every shipped
change auto-marks itself on the chart. The command exits with a
distinct code on a plan-limit (4) or duplicate (5) error so your
pipeline can handle each case. See the
CLI integration guide
for the full flag reference and a GitHub Actions example.
Option 3 - REST API
There is also a /api/annotations endpoint that the dashboard itself
uses. It authenticates with your dashboard session (the same login you
use in the browser), so it's only practical for a server that already
holds a valid session. External zv_* API keys are not accepted on
this endpoint today, so for CI and other automated environments the CLI
above is the right tool - it handles authentication for you. See the
Chart Annotations API reference
for the full request and response shape.
Plan limits and behaviour
- Free: 10 annotations per team per month.
- Pro and above: unlimited annotations.
An annotation with the same type and the same message within 5
minutes of an existing one is rejected so a misconfigured CI pipeline
replaying the same payload can't flood the timeline. Two annotations of
the same type with different messages (for example "checkout broke" then
"checkout fixed") are both allowed.
Where annotations appear
Once created, an annotation shows up in three places:
- Below every customer-facing analytics chart as a colored chip strip. Hover the chip to see the full message and exact time.
- In the conversion incident triage panel as a "suspect change" when the annotation falls within ±2 hours of an incident's start. Helps the AI triage answer "what changed near this drop?".
- On the legacy notes icon position on the domain visitor chart, if you've used the older notes feature before. Both surfaces stay in sync automatically.
Reading the chip strip
Each chip below a chart is color-coded by type, with the type icon on the left. The five colors stay consistent across every chart and every page, so once you learn them you can scan the strip at a glance: a cluster of blue means deploys, amber means campaigns, red means incidents. The chip shows the message you wrote and the time it was created; hover over a chip for the full timestamp.
Privacy: public dashboards never show annotations
If you've shared a public dashboard link with someone outside your team, annotations are hidden on that view. Deploy and release messages are intended for the team operating the site, not for visitors. There is no way to expose annotation messages publicly.
Common patterns
Mark every production deploy automatically Add the CLI command as a post-deploy step so every shipped change marks itself. Zero manual work after the first wire-up.
Mark a marketing campaign launch
Run zenovay annotation create --type=campaign --message="Spring sale launch"
the moment the campaign goes live. When you review the campaign's
traffic lift later, the marker is already on the chart.
Mark a known incident If you know an outage or partial degradation occurred, post an incident annotation so the chart visibly explains the dip. Pairs naturally with the conversion incident triage which auto-detects unexplained drops.
Troubleshooting
- "Annotation limit reached": you're on the Free plan and have used your 10 monthly annotations. Upgrade to Pro for unlimited.
- HTTP 409 dedup error: you're trying to post an annotation with the same type and the same message within 5 minutes of an existing one. Either wait, change the message, or accept that the first marker already represents the event. (The CLI returns exit code 5 for this case.)
- The chip strip doesn't show under my chart: confirm you've created at least one annotation for that website. The strip is hidden when there's nothing to show.
- The chip is in the wrong language or theme: theme follows the dashboard's theme; language follows your browser's locale. Both switch automatically.