/managing-subscriptions

name: managing-subscriptions
description: >
  Create and manage scheduled PostHog subscriptions for insight snapshots,
  dashboard snapshots, and AI prompt reports. Use when a user wants recurring
  email, Slack, or Microsoft Teams delivery; an AI summary; delivery history;
  schedule or recipient changes; a test delivery; pause, resume, or deletion;
  or help with subscription permissions, limits, billing, and failures. Use
  product alerts when delivery must depend on a threshold or anomaly.

Managing subscriptions

Subscriptions deliver product data on a fixed schedule. They support insight snapshots, dashboard snapshots, and AI prompt reports.

Read the relevant references

• Read [subscription-types.md](references/subscription-types.md) before you select or change a resource type.
• Read [destinations.md](references/destinations.md) before you create or change a destination.
• Read [operations.md](references/operations.md) for schedules, limits, billing, delivery checks, and failures.
• Use `creating-ai-subscription` for the detailed prompt report creation workflow.

Choose the correct product

• Use a subscription for fixed delivery, such as "send this dashboard every Monday."
• Use a product alert for a condition, such as "notify me when conversion falls below 10%."
• Use a reminder when the user wants a private prompt to inspect a resource later.
• Use a Signals scout when an agent must decide what is important to report.

Subscriptions do not evaluate thresholds, recovery, consecutive breaches, or quiet hours. Snapshot subscriptions attempt each scheduled occurrence even when the saved results do not change.

Tools

| Tool | Purpose | | -------------------------------------------- | --------------------------------------- | | `posthog:subscriptions-list` | Find subscriptions | | `posthog:subscriptions-retrieve` | Read one subscription | | `posthog:subscriptions-create` | Create a subscription | | `posthog:subscriptions-partial-update` | Change, pause, or resume a subscription | | `posthog:subscriptions-test-delivery-create` | Send a test delivery | | `posthog:subscriptions-deliveries-list` | List delivery attempts | | `posthog:subscriptions-deliveries-retrieve` | Read one delivery | | `posthog:subscriptions-delete` | Stop all future deliveries | | `posthog:integrations-list` | Find a Slack integration | | `posthog:integrations-channels-retrieve` | Find Slack channels | | `posthog:dashboard-get` | Read dashboard tiles | | `posthog:insight-get` | Resolve an insight ID |

Create a subscription

1. Call `posthog:subscriptions-list` and check for a duplicate. 2. Select one resource type from [subscription-types.md](references/subscription-types.md). 3. Resolve the destination with [destinations.md](references/destinations.md). 4. Resolve the schedule with [operations.md](references/operations.md). 5. Ask whether the user wants an immediate delivery. 6. Set `send_test_now` to the user's choice. 7. Call `posthog:subscriptions-create`. 8. Read the saved subscription and check each requested field. 9. If the user approved an immediate delivery, check its delivery record.

If creation times out or returns an uncertain result, list matching subscriptions before you retry. Creation is not idempotent. A blind retry can create a duplicate subscription and send a duplicate immediate delivery.

Do not infer missing recipients, channels, times, or time zones. Ask for these values before creation.

Find existing subscriptions

Use these list filters when they reduce ambiguity:

• `resource_type`: `insight`, `dashboard`, or `ai_prompt`.
• `target_type`: `email`, `slack`, or `teams`.
• `insight` or `insights`: One insight ID or a comma-separated ID list.
• `dashboard`: One dashboard ID.
• `dashboard_tiles`: Insight subscriptions for live tiles on one dashboard.
• `created_by`: One creator UUID.

Check for duplicates

Use `search` when the user supplied a title, insight name, dashboard name, or prompt text. Prompt subscriptions match their title and prompt text. Compare the resource, destination type, target, schedule, and enabled state.

A Teams result contains only the webhook host. One host can serve many channels. Do not use the host to identify a duplicate.

Show the title, schedule, creator, and creation date for possible Teams matches. Ask the user to select a subscription when these fields identify it. Create a new subscription when no field identifies the target channel.

Confirm the saved result

Check these fields after creation:

• `resource_type` matches `insight`, `dashboard`, or `ai_prompt`.
• `target_type` and the safe target label match the request.
• `enabled` is `true`.
• `next_delivery_date` matches the schedule and time zone.
• The AI and delivery options match the user's choices.

Change a subscription

Call `posthog:subscriptions-retrieve` before each update. Before an update that can send a delivery, list the current delivery IDs. Then call `posthog:subscriptions-partial-update` with the changed fields.

Ask before an update that can send an immediate delivery. The MCP update tool cannot suppress an immediate delivery for these changes. If the user does not approve delivery, do not make the update.

• Set `enabled: false` to pause delivery.
• Set `enabled: true` to resume delivery.
• Send the complete new target when you change recipients.
• Send `target_type` and `target_value` together when you change the destination type.
• Omit `target_value` to keep a saved Teams webhook URL.
• Send the full new Teams webhook URL when you replace it.

Th