Annotations

Vertical markers on every chart that let you see exactly what happened — and when — without leaving your dashboard.

What annotations do

An annotation is a timestamped label you attach to a moment in time. Once created, Produl draws a vertical dashed line at that timestamp across every time-series chart for that site — pageview trend, visitor count, bounce rate, custom event charts, and more.

The result: instead of asking "why did traffic jump on Tuesday?", you see the line, hover it, and read "Launched homepage redesign — 2.0". No context-switching, no log-diving.

Annotations are stored per-site. They are visible to everyone on the team who has access to that site.

Common use cases

Annotations are useful any time you want to correlate a change in your metrics with something that actually happened. Here are real examples of what teams annotate:

Shipping a new feature or redesign

You deploy a new pricing page. Traffic to /pricing spikes 40%. Without an annotation you might not know whether that spike was the new page, a tweet, or a coincidence. With an annotation labelled "Pricing page redesign — v2", the cause is visible at a glance.

Running a marketing campaign

You launch a Google Ads campaign or publish a blog post that goes viral. Annotate the start date so you can separate organic baseline from campaign-driven traffic. When the campaign ends, annotate that too — it makes the drop-off self-explanatory.

# Mark the start of a paid campaign
curl -X POST https://app.produl.tech/api/sites/SITE_ID/annotations \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Google Ads campaign — Q2 launch",
    "description": "Budget: $5k/mo, targeting: SaaS founders",
    "committed_at": "2025-06-01T09:00:00Z"
  }'

# Mark the end of the campaign
curl -X POST https://app.produl.tech/api/sites/SITE_ID/annotations \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Google Ads campaign — ended",
    "committed_at": "2025-06-30T23:59:59Z"
  }'

A pricing change

You raise or lower prices. Annotate the exact moment. Now you can measure the before/after effect on conversion rate, bounce rate on the pricing page, or session duration — with a clear boundary drawn on the chart.

A bug, incident, or outage

Your checkout broke for 2 hours on a Thursday afternoon. Annotate the start and the fix so the dip in conversions has an explanation — and so you can verify the fix actually worked by watching the recovery in real-time.

# Mark when an incident started
curl -X POST https://app.produl.tech/api/sites/SITE_ID/annotations \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Incident: checkout broken",
    "description": "Payment provider 502 — users unable to complete purchase",
    "committed_at": "2025-06-12T14:22:00Z"
  }'

# Mark the resolution
curl -X POST https://app.produl.tech/api/sites/SITE_ID/annotations \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Incident resolved",
    "description": "Payment provider recovered, checkout functional",
    "committed_at": "2025-06-12T16:05:00Z"
  }'

A/B test start and end

Running an experiment on your landing page headline? Mark when the test started and when you called a winner. You can compare the before and after periods directly on the chart.

Creating annotations

Via the API

The API lets you create annotations programmatically — from CI pipelines, deployment scripts, or any automation. Use your site's server-side API key (found under Settings → Tracking → Server Keys).

curl -X POST https://app.produl.tech/api/sites/SITE_ID/annotations \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "v3.1.0 deployed",
    "description": "New onboarding flow + faster checkout",
    "committed_at": "2025-09-15T11:30:00Z"
  }'

Fields:

• title (required) — short label shown on the chart line and tooltip
• description (optional) — more detail shown in the hover panel
• committed_at (optional) — ISO 8601 timestamp; defaults to now if omitted

Integrating with your deploy pipeline

A common pattern is to add an annotation step at the end of your CI/CD pipeline. Here's an example using GitHub Actions:

- name: Annotate Produl
  run: |
    curl -X POST https://app.produl.tech/api/sites/${{ secrets.PRODUL_SITE_ID }}/annotations \
      -H "Authorization: Bearer ${{ secrets.PRODUL_SERVER_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Deployed ${{ github.ref_name }}",
        "description": "${{ github.event.head_commit.message }}"
      }'

Via the dashboard

Go to Site Settings → Annotations. Fill in a title, optional description, and optional date/time. Leave the date blank to annotate right now. Annotations created here appear on charts immediately.

How they appear

Every time-series chart on the site dashboard shows a vertical dashed line at each annotation's timestamp. The line colour matches the chart accent. Hovering the line shows a tooltip with the title and description. The annotation is the same across all chart types — pageviews, visitors, events, bounce rate, and session duration.

Annotations are only shown for the time range currently displayed. If you're looking at the last 7 days, annotations older than 7 days won't appear.

Tips

• Pair two annotations for ranges. For events with a clear start and end (campaigns, experiments, incidents), create one annotation for the start and one for the end. The gap between the two lines is your event window.
• Keep titles short. The tooltip truncates long titles. Aim for under 40 characters. Use the description field for detail.
• Combine with Web Vitals. Annotations on the Web Vitals chart make it immediately obvious if a deploy degraded Core Web Vitals scores.
• Use ISO 8601 for precision. The committed_at field accepts full ISO timestamps including timezone offset: 2025-06-01T14:00:00-07:00 for PDT, for example.