Annotations

What triggers an annotation

Five callsites push an annotation to Amplitude. All five fire asynchronously (fire-and-forget) so they never block the action that triggered them.

• Bet promoted from hypothesis — when a hypothesis is promoted to a Bet, Findry immediately pushes a "▲ Bet promoted" annotation at the current timestamp.
• Bet status → shipped (manual) — when a PM manually marks the bet as shipped in the bet detail view.
• Outcome ship date set — when a PM sets or updates the ship date on an Outcome, an annotation is pushed at that date.
• Tracker auto-detects ship date — if a linked Jira / Linear ticket moves to "Done," Findry auto-sets the ship date and the annotation fires automatically.
• Outcome verdict assigned — when the outcome-sweep cron assigns a verdict (hit / miss / inconclusive), or when a PM overrides the verdict manually. Annotation pushed at the measurement timestamp.

How annotations look in Amplitude

Amplitude shows annotations as labeled vertical lines on every chart in the project — the same chart you're already watching for metric changes. You don't need to navigate anywhere; the markers appear automatically on the timeline.

Label formats:

• Bet promoted: ▲ [Bet title]
• Bet shipped: ▲ Shipped: [Bet title]
• Outcome verdict: ● Outcome [verdict]: [Bet title] — for example, "● Outcome hit: Mobile checkout conversion"

Labels are set at annotation create time and updated if the bet title changes — the PATCH path handles updates via the same idempotent flow described below.

Toggle push on / off

Annotation push defaults ON at connect time. To disable it:

Settings → Integrations → Amplitude tile → Push annotations toggle

Toggling off stops future pushes immediately. Existing annotations in Amplitude are not deleted — they stay as historical context. Toggling back on resumes push; no back-fill of the gap period.

Every toggle change writes an amplitude.push_annotations_set event to the workspace audit log with the actor and new value.

Re-fires + idempotence

Each (bet, event_type) pair is tracked in an amplitude_annotation_pushes row. When a callsite fires:

• If no row exists → POST /api/2/annotations → insert row with the new annotation ID.
• If a row exists → PATCH /api/2/annotations/[id] → update the label and date if they changed.
• If Amplitude returns 404 on PATCH (annotation was manually deleted in Amplitude) → re-create via POST → update the tracking row with the new ID.

The practical consequence: re-running a workflow step (editing a bet title, re-computing an outcome, toggling push off/on) never creates duplicate annotations in Amplitude. At most one annotation per (bet, event_type) exists at any time.

Audit trail

Every annotation push attempt writes to the workspace audit log. You can view it at Settings → Audit log — filter by actor or action.

• amplitude.annotation_pushed — successful push or PATCH, includes annotation ID and bet ID.
• amplitude.annotation_failed — push failed (network error, 4xx from Amplitude other than 404). Includes the error code and message. The bet workflow continues regardless; annotation failure is non-fatal.

Investigating a missing annotation

If you expect an annotation in Amplitude but don't see it: check the audit log for an amplitude.annotation_failed event around the time the bet event occurred. The event payload includes the Amplitude error code — a 401 means the API key was rotated without reconnecting Findry; a 429 means Amplitude rate-limited the push; a 5xx means Amplitude was temporarily down.

No inbound flow

Unlike the PostHog integration, there is no inbound data flowing from Amplitude into Findry. Amplitude doesn't ship a first-party survey product, so the PostHog Surveys → Findry Signals pattern has no Amplitude equivalent.

If your team uses a survey tool alongside Amplitude (Sprig, Typeform, Delighted, SurveyMonkey), Signals can still be created from survey responses via:

• Manual entry — paste the response text directly into a Signal and link the source URL.
• Webhook — if your survey tool can POST to a webhook, the Findry Signals API accepts inbound payloads. See the Signals guide for the webhook shape.