Source: https://datafa.st/docs/api/account/notes/list
Markdown source: https://datafa.st/docs/api/account/notes/list.md
Description: List manual chart notes, with date filtering, text search, and pagination.

# List notes

`GET https://datafa.st/api/v1/admin/websites/{websiteId}/notes`

List manual chart notes, with date filtering, text search, and pagination.

Required account-token permission: `notes:read`.

## Query parameters

| Parameter | Type | Description |
|---|---|---|
| `startAt` / `endAt` | string | Supply together. Inclusive YYYY-MM-DD dates or ISO timestamps with Z/offset. Defaults to the last 30 calendar days, including today. |
| `timezone` | string | IANA timezone; defaults to the website timezone. Date-only bounds include the entire local day. |
| `q` | string | Case-insensitive text search, up to 200 characters. |
| `limit` | integer | Page size, 1–1000; default 100. |
| `offset` | integer | Rows to skip; default 0. |
| `order` | string | `desc` (newest first, default) or `asc`. |

Pagination returns `limit`, `offset`, `total`, and `hasMore`. Unknown or duplicate query parameters are rejected.
## Response

`data` is an array of manual notes. Each note includes `id`, `websiteId`, `text`, `timestamp` (UTC ISO), `author` (`id`, `name`, `image`, or null if the author was deleted), `createdAt`, and `updatedAt`. The author is derived from the authenticated account; it cannot be supplied by the caller.

API-created notes appear on the existing dashboard chart at their timestamp. They remain visible when changing the chart's period or granularity, subject to the chart's note visibility toggle. Manual notes are private to authorized website users; public dashboard responses do not expose them.

MCP: `datafast_notes_list`.
## Authentication

Use `Authorization: Bearer df_...` for one website, or `dft_...` with the required permission and website access. Notes always require `websiteId` in the path. Mention reads infer it from a website key; account tokens must provide the `websiteId` query parameter.

Existing website keys and `*` account tokens work automatically. For restricted account tokens, open [Account settings → API](/dashboard/settings?tab=api), expand your token, choose **Edit permissions**, and enable **Notes → Read / Write**. Save permissions to keep the same token and MCP connection. Only the signed-in token owner can edit permissions in the dashboard; no API or MCP operation can do this.

## Errors

Standard errors use `{ "status": "error", "error": { "code": 400, "message": "..." } }`. Expect `400` for invalid fields, dates, or IDs; `401` for invalid credentials; `403` for missing permissions or website access; `404` for a missing website/note; `409` for reusing a creation key with different input; and `429` for the normal API rate limit.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/admin/websites/{websiteId}/notes" \
  -H "Authorization: Bearer dft_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [
    {
      "id": "69a123456789012345678901",
      "websiteId": "65f123456789012345678901",
      "text": "Launched the new landing page",
      "timestamp": "2026-09-05T10:00:00.000Z",
      "author": {
        "id": "65f123456789012345678902",
        "name": "Marc",
        "image": null
      },
      "createdAt": "2026-09-05T10:01:00.000Z",
      "updatedAt": "2026-09-05T10:01:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1,
    "hasMore": false
  }
}
```