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 title. This is 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").

Omit organization. The server fills it from the active organization.

Pass organization only when the user names a different organization and gives you its ID. If the user names one but gives no ID, ask for the ID before you continue. Do not guess the value, and do not omit the field instead: an omitted organization puts the reminder in the active organization, not the one the user named.

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.

User says	Field
"remind me tomorrow at 3pm"	scheduled_at: <tomorrow 15:00 in the user's tz>
"remind me on Jan 5 at 9am"	scheduled_at: "2026-01-05T09:00:00" (+ timezone)

Preset recurring

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

User says	Field
"every day"	recurrence_interval: "daily"
"every week"	recurrence_interval: "weekly"
"every month"	recurrence_interval: "monthly"
"every year"	recurrence_interval: "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.

User says	Field
"every Monday at 9am"	cron_expression: "0 9 * * 1"
"weekdays at 8:30"	cron_expression: "30 8 * * 1-5"
"1st of the month at noon"	cron_expression: "0 12 1 * *"

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).

resource_type	resource_id is the…
dashboard	numeric id
insight	short_id
experiment	numeric id
feature_flag	numeric id
survey	id
notebook	short_id
replay	session_id
error_tracking	issue id

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 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 title:

{
  "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.