managing-reminders

Managing reminders

This skill guides you through creating and managing PostHog reminders. A reminder is a private, human-paced nudge to yourself: it fires an in-app notification on a schedule, with no condition attached. It can optionally link to a PostHog resource.

When to use this skill

Use this skill when the user:

• Says "remind me to…", "nudge me", "ping me", or "don't let me forget"
• Wants a one-off reminder at a specific date/time
• Wants a recurring reminder (every day, weekly, every Monday, weekdays, monthly, etc.)
• Wants to be reminded to review a specific dashboard, insight, experiment, flag, survey, notebook, replay, or error
• Wants to see, change, or cancel reminders they have set

Reminder vs alert vs subscription

These three look similar but solve different jobs. Pick the right one:

• Reminder — a human-paced nudge to yourself with no condition. It just fires an in-app notification on a schedule ("remind me to review the launch dashboard every Monday"). If the user says "remind me to…", it is a reminder.
• Alert — watches an insight's metric on a schedule and notifies only when a threshold or anomaly condition is met ("tell me if signups drop below 100").
• Subscription — delivers an insight or dashboard export/snapshot on a schedule via email, Slack, or webhook ("email me this dashboard every morning").

If there is a condition to evaluate, it is an alert. If there is an export to deliver, it is a subscription. If it is just a timed nudge to a person, it is a reminder.

Required fields

Every reminder-create call must include both of these fields. A call without them is rejected.

• organization — the organization ID (a UUID string). Call organization-get with no arguments to get the active organization, and use its id. Do not guess this value. If organization-get fails because no organization is selected, call organizations-list. If the user belongs to one organization, use its id. Otherwise, ask the user which one to use, then call switch-organization with it.
• title — the short text shown as the notification title. Write it from the user's request (for "remind me to review the launch dashboard", use "Review the launch dashboard").

Also set team (the numeric project ID) whenever you know the project. It is required when you attach a resource, and it makes the project timezone the default.

Scheduling shapes

A reminder uses exactly one of scheduled_at, recurrence_interval, or cron_expression. Providing zero or more than one is rejected.

One-off

Set scheduled_at to a future ISO 8601 timestamp. The reminder fires once, then becomes completed.

Preset recurring

Set recurrence_interval to one of daily, weekly, monthly, yearly.

Cron recurring

Set cron_expression to a 5-field cron string (min hour day-of-month month day-of-week) when the cadence is a specific weekday or time the presets can't express.

A reminder may fire at most 4 times per day — a more frequent cron (e.g. hourly) is rejected.

Timezone

Always pass timezone as the user's IANA zone (e.g. "America/New_York") when you know it, so wall-clock times like "9am" resolve to the right moment. If omitted, it defaults to the project timezone when team is set, otherwise to UTC. Cron and preset schedules resolve in this zone; scheduled_at is an absolute instant, so include its offset or rely on the same zone.

Attaching a resource

To link the reminder to a PostHog object, set resource_type, resource_id, and team together. The fired notification deep-links to that object. The resource must already exist in that project. Always send resource_id as a string, even when the ID is numeric ("67", not 67).

Resolve the id first if the user gives you a name or URL (e.g. fetch the insight to get its short_id). Omit both fields for a standalone reminder with no linked resource.

Privacy and lifecycle

• Reminders are private to the creating user and belong to an organization, optionally scoped to one project. Other users never see them.
• They fire as in-app notifications — not email, Slack, or webhook.
• A one-off becomes completed after it fires.
• A recurring reminder stays active until deleted, or until its optional end_date passes (then it becomes completed).
• A one-off whose delivery permanently fails becomes errored — surface this via reminders-list when reporting on a user's reminders.

The MCP tools

• reminder-create — create a reminder
• reminders-list — list the user's reminders (schedule, status, next fire time)
• reminder-get — get one reminder by id
• reminder-update — update title, message, schedule, timezone, end date, or attached resource (changing the schedule recomputes the next fire time)
• reminder-delete — delete a reminder, which stops it firing

Worked example

User: "Remind me to review the launch dashboard every Monday at 9am."

1. Get the organization ID with organization-get and the project ID from the active project.
2. Resolve the dashboard id (e.g. dashboard 67).
3. Pick the schedule shape: a specific weekday + time → cron.
4. Pass the user's timezone if known.
5. Call reminder-create with the required organization and title:

{
  "organization": "0188a0b2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "team": 12345,
  "title": "Review the launch dashboard",
  "resource_type": "dashboard",
  "resource_id": "67",
  "cron_expression": "0 9 * * 1",
  "timezone": "America/New_York"
}

Confirm back to the user when it will next fire (use next_fire_at from the response), and that it will keep firing weekly until they delete it.