Chart annotations

Annotations explain why traffic, conversions or performance changed. They appear across Overview, Campaigns, Events, Funnels, Retention and Performance for every member of the site.

Add an annotation#

Site owners and managers can select Add annotation above an analytics report. Choose a start time, an optional end time, a category and a short title. Use a date range for incidents or campaigns and a single timestamp for releases and product changes.

PureStats uses the site's configured timezone when saving and displaying annotation times. Automatically generated import boundaries and known data gaps are read-only so their operational history stays intact.

Deployment API#

CI systems can create or update deployment markers without a browser. Use a site API key whose permissions include annotations:write, write or *.

curl -X POST https://purestats.io/api/v1/annotations/deployments \
  -H "Authorization: Bearer $PURESTATS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "release-2026-09-21.1",
    "deployed_at": "2026-09-21T11:30:00Z",
    "title": "Release 2026-09-21.1",
    "description": "Checkout and navigation update"
  }'

external_id is idempotent per site. Sending it again updates the existing marker instead of creating a duplicate. If omitted, PureStats generates a unique ID.

Successful responses use HTTP 201 for a new deployment and HTTP 200 for an update:

{
  "success": true,
  "data": {
    "id": 42,
    "status": "created"
  }
}

API keys are restricted to their own site. Keep them in the secret store of the deployment system and never include them in source code, URLs or build logs.