Chart notes

Mark releases, launches and incidents on your charts so changes in traffic, conversions and revenue have context.

How notes appear

Each note is a dated label on one website. On the Overview chart it shows as a dashed marker colored by type, and hovering that point shows the note in the tooltip. The note count next to All metrics opens every note in the selected period.

Note types
Release
Deploys, new features and pricing changes.
Marketing
Launches, campaigns, newsletters and press.
Incident
Outages, broken checkout or tracking gaps.
Other
Anything else worth remembering.
A note near a change is context, not proof that it caused the change.

Add a note in the dashboard

  1. 1

    Open Overview

    Choose the website and a date range that includes the moment you want to mark.

  2. 2

    Open notes

    Click the note count or Add note next to All metrics.

  3. 3

    Describe the moment

    Write up to 120 characters, choose the date and time, the type and an optional link, then save.

Workspace owners and website admins can add, edit and delete notes. Everyone with access to the website can see them.

Add notes from your deploy pipeline

Create a key in Settings → Developer with the permission Add chart notes only and one website. Notes keys start with tw_nw_. They can only add notes to that website; they cannot read analytics, connect to MCP or change anything else. Store the key as a CI secret, never in source control.

Terminal
curl -X POST "https://tracwell.app/api/notes?projectId=YOUR_WEBSITE_ID" \
  --header "Authorization: Bearer $TRACWELL_NOTES_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"requestId\":\"$(uuidgen)\",\"occurredAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"label\":\"Deploy $GIT_SHA\",\"category\":\"release\"}"
GitHub Actions step
- name: Add a Tracwell deploy note
  if: success()
  continue-on-error: true
  env:
    TRACWELL_NOTES_KEY: ${{ secrets.TRACWELL_NOTES_KEY }}
  run: |
    curl --fail-with-body -X POST "https://tracwell.app/api/notes?projectId=YOUR_WEBSITE_ID" \
      --header "Authorization: Bearer $TRACWELL_NOTES_KEY" \
      --header "Content-Type: application/json" \
      --data "{\"requestId\":\"$(uuidgen)\",\"occurredAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"label\":\"Deploy ${GITHUB_SHA::7}\",\"category\":\"release\"}"

Find the website ID in the dashboard URL as projectId. Keep the step after a successful deploy, and let a failed note not fail the release, as in the example.

Notes API

POST /api/notes?projectId=WEBSITE_ID
Authorization
Bearer with a notes key, or a website write key
requestId
A new UUID per note. Reuse it unchanged when retrying; the retry returns the original note.
occurredAt
When it happened, as an ISO 8601 timestamp with a time zone.
label
1 to 120 characters.
category
release, marketing, incident or other. Defaults to other.
url
Optional http(s) link, such as a changelog or pull request.
201 Created
{
  "note": {
    "id": "6d1f3c2e-8b7a-4c1d-9e0f-2a3b4c5d6e7f",
    "projectId": "YOUR_WEBSITE_ID",
    "occurredAt": "2026-10-20T09:30:00.000Z",
    "label": "Deploy 88a17d2",
    "url": null,
    "category": "release",
    "source": "api",
    "createdAt": "2026-10-20T09:30:02.114Z",
    "updatedAt": "2026-10-20T09:30:02.114Z"
  }
}
Errors
400
The body is invalid, for example a label over 120 characters.
401
The key is missing, revoked, or belongs to another website.
403
The key cannot add notes, or the workspace has no active plan.
409
The request ID was already used with different input, or the website has 5,000 notes.
429
Too many requests. Retry later with the same request ID.

Use notes with an AI assistant

Through MCP, every connection can list notes with notes_list, so an assistant can explain a spike with the launch that preceded it. Write keys and OAuth connections approved for writing can also add one with note_create. Ask an assistant to add a note only when you mean it.

Limits

  • Labels are 1 to 120 characters; links up to 2,048.
  • A website keeps at most 5,000 notes. Delete old notes to add more.
  • Notes need an active plan, including trials and complimentary access, and are deleted with their website.