> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 04.24.2026 Trace Notes API

> Add trace notes via REST endpoint, TypeScript client, or CLI; reserve the note annotation name for note-specific APIs.

## Trace Notes API

**Available in arize-phoenix 14.13.0+ (server), @arizeai/phoenix-client 6.8.0+ (TypeScript), @arizeai/phoenix-cli 1.3.0+ (CLI)**

Phoenix now supports creating trace notes through a dedicated REST endpoint, TypeScript client function, and CLI command. Notes are stored separately from annotations — each trace can hold multiple notes, and `--include-notes` keeps them out of the annotations view.

To keep note behavior consistent, the reserved annotation name `note` is no longer accepted on the generic annotation endpoints. Use the dedicated note endpoints instead:

* `POST /v1/trace_notes` for trace notes
* `POST /v1/span_notes` for span notes

## TypeScript

```typescript theme={null}
import { addTraceNote } from "@arizeai/phoenix-client/traces";

const result = await addTraceNote({
  traceNote: {
    traceId: "abc123def456",
    note: "Needs follow-up review.",
  },
});
console.log(result.id); // note annotation ID
```

## CLI

```bash theme={null}
# Add a note to a trace
px trace add-note <trace-id> --text "Needs follow-up review."

# Fetch a trace with its notes
px trace get <trace-id> --include-notes

# List traces with notes
px trace list --include-notes
```

Notes appear under `notes[]` on the trace object (distinct from `annotations[]`) when you pass `--include-notes`.