---
title: "Chart notes - Tracwell docs"
description: "Mark releases, launches and incidents on your charts from the dashboard, a deploy pipeline or an AI assistant."
canonical: "https://tracwell.app/docs/notes"
markdown: "https://tracwell.app/docs/notes.md"
---

# 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

```bash
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

```yaml
- 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

```json
{
  "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](https://tracwell.app/docs/agents) , 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.