Web Analytics

List annotations

GET https://demo.notifuse.com/api/annotations.list

Returns the workspace's annotations, most recent moment first. Every filter is optional; with none the most recent 100 rows come back.

Gated by the web_analytics read permission, like the rest of the web analytics surface.

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Query Parameters

workspace_id string required

The ID of the workspace

Example ws_1234567890
start string<date-time>

Only annotations at or after this instant. Must be RFC3339; a malformed value is a 400 rather than a dropped filter.

Example 2026-08-01T00:00:00Z
end string<date-time>

Only annotations at or before this instant. Must be RFC3339.

Example 2026-08-31T23:59:59Z
sources string

Comma-separated list of sources to keep. Any value outside manual/broadcast is a 400.

Example manual,broadcast
limit integer

Maximum rows to return. Values above the maximum are clamped to it rather than refused.

Default 100 Max 1000 Example 100

Response

200 Annotations matching the filters object
annotations object[]
Show 10 child attributes Hide 10 child attributes
id string required

Server-generated identifier (a UUID with its dashes removed).

Example 3f2504e04f8911d39a0c0305e82c3301
annotated_at string<date-time> required

The moment the annotation marks, as a real instant.

Example 2026-08-15T09:00:00Z
timezone string required

IANA timezone the moment was entered in. This is display intent only — annotated_at already fixes the instant, and filtering never uses this field. It is what lets "9am in Tokyo" render back as 9am instead of the reader's local equivalent.

Example Asia/Tokyo
title string required

Counted in characters, not bytes.

Max length 100 Example Pricing page redesign
description string

Optional longer note. Counted in characters, not bytes.

Max length 500 Example Rolled out to all visitors after the A/B test.
color string required

Six-digit hex colour used for the marker on the charts.

Example #3b82f6
source string required

Who wrote the row. manual is anything typed by an operator or posted to this API; broadcast rows are written automatically when a broadcast starts sending. There is deliberately no API source — see the note on annotations.create.

Options manual, broadcast Example manual
source_id string

The entity that caused an automatic annotation (a broadcast id today). Always absent on manual rows, and never settable through the API. An annotation outlives the entity it points at: deleting a broadcast leaves its annotation, because the send did happen.

Example bcast_1234567890
created_at string<date-time> required
updated_at string<date-time> required
400 Bad request - invalid query parameters object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

403 Forbidden - missing required permission object
error string required

Error message

500 Internal server error object
error string required

Error message