#Annotations and deploy markers

Annotations explain jumps in a chart. Each one is a small flag on the day it happened, with a dashed line through the chart; hovering, tapping or focusing the flag shows what happened. They appear in every time series of the dashboard (Quellen & Kampagnen, Verhalten, Search Console) and in the KPI sparklines of Pulse.

Rights: everybody who can see the project sees its annotations (viewers read-only). Adding, editing and deleting needs config:write or ads:write (analyst and up). Notes for every project of the organization (scope: "org") need org:admin. Every change is written to the audit log (annotation.created, annotation.updated, annotation.deleted).

#Manual notes

In the dashboard: Einstellungen › Anmerkungen & Deploys › „Notiz hinzufügen“. A note has a title (max. 120 characters), an optional text (1000) and link, a time and – for a period such as a promotion week – an end. Via the API:

POST /v1/projects/{project}/annotations
{
  "title": "Herbst-Aktion",
  "at": "2026-10-05T08:00:00+02:00",
  "endsAt": "2026-10-11T22:00:00+02:00",
  "body": "20 % auf alle Erstberatungen",
  "link": "https://example.com/herbst"
}

• GET /v1/projects/{project}/annotations?from=2026-10-01&to=2026-10-31&kind=manual,deploy lists the markers overlapping the range (project days, oldest first; org-wide notes included unless include_org=false; limit up to 500 with nextCursor).
• PATCH /v1/projects/{project}/annotations/{id} needs the version you read. If someone else changed the note meanwhile, the answer is 409 annotation_conflict with the current state in current – reload, re-apply, send again.
• DELETE /v1/projects/{project}/annotations/{id} removes it from every chart. Org-wide notes are also listed and deleted at /v1/orgs/{org}/annotations.
• A double-click (the same title and time by the same author within 15 seconds) creates one note, not two; Idempotency-Key works as on every create endpoint.

#Deploy markers

Create a webhook in Einstellungen › Anmerkungen & Deploys › „Deploy-Webhook“ (project:admin). The URL with its token is shown once; X3 stores only a hash. Call it from your pipeline after a successful deploy – the body is optional:

curl -fsS -X POST "https://api.x3growth.io/v1/hooks/deploy/x3d_…" \
  -H "content-type: application/json" \
  -d '{"version":"v1.4.2","commit":"'"$GIT_SHA"'","environment":"production","service":"website"}'

• An empty POST marks „Deploy“ now. Optional fields: title, at, version, commit (7–40 hex), environment, service, link.
• The same commit with the same service and environment is one marker: CI retries answer 200 with the existing id instead of 201.
• At most 30 calls per token and minute (429 with Retry-After), body up to 16 KiB, at most 10 active webhooks per project. Unknown or revoked tokens answer 404.
• With a secret key, POST /v1/projects/{project}/annotations with "kind": "deploy" does the same.
• A new marker also starts a new page version for heatmaps and recordings („Wirkung einer Änderung“, the alert behavior_deploy_drop, a re-crawl of the most visited pages). GitHub and Vercel webhooks that sign with a secret instead of a token use the page-version hook POST /v1/hooks/page-version/{project} (HMAC-SHA256 in x-x3-signature or x-hub-signature-256; secret under Einstellungen › Aufnahmen & Heatmaps).

#Automatic markers

• Campaign start and stop. Each ad sync compares the campaigns' status with the last sync: paused → active is a start, active → paused/ended/removed a stop. Campaigns that existed before X3 synced them get their start from their first day with spend – but only when that day lies after the first synced day of the account (otherwise the real start is unknown and no marker is shown). Transitional states (in review, with issues) never create a marker.
• Budget changes of active campaigns (and of ad sets that hold the budget, as on Meta and LinkedIn), in the account currency. More than 25 changes in one sync are summed up in one marker.
• X3 settings: applying a template, goals, interest score, tracking settings (domains, page groups, consent, auto-capture …) and the monthly budget. Several saves of the same setting by the same person within 10 minutes merge into one marker.
• The attribution model („Zählweise“) is a personal view setting of each member, not a project setting – switching it changes no data and writes no marker.

Deleting an automatic marker hides it for good: the next sync does not create it again.

#MCP

annotations_list, annotations_create, annotations_update and annotations_delete – see MCP tools. Ask „What changed around 5 October?“ and Claude reads the markers next to the numbers.