/creating-ai-subscription

name: creating-ai-subscription
description: >
  Create a recurring AI-generated PostHog report — schedule a free-text prompt to
  run on a cron, with the LLM-synthesized markdown delivered to email, Slack, or Microsoft Teams
  on each tick. Use when the user wants a recurring AI summary of X on any cadence
  (daily, weekly, monthly, yearly) rather than a one-off report. (To attach an AI
  summary to an existing insight/dashboard
  subscription instead of a free-text prompt, see `managing-subscriptions` and its
  `summary_enabled` option.)

Creating a prompt subscription

When to use this

A **subscription** delivers a PostHog report to email, Slack, or Microsoft Teams on a recurring schedule. There are three kinds, distinguished by which field you set — the kind is derived and returned as the read-only `resource_type`:

• **`insight`** — periodic snapshots of one existing insight (`resource_type: "insight"`)
• **`dashboard`** — periodic snapshots of a dashboard's tiles (`resource_type: "dashboard"`)
• **`prompt`** — a recurring **AI-generated** report from a free-text prompt: an LLM

plans and runs HogQL over the project's data and synthesizes a fresh markdown report each tick (`resource_type: "ai_prompt"`)

Use **this** skill for the **prompt** kind — i.e. when the user wants a recurring AI summary of X (on any cadence — daily, weekly, monthly, yearly) rather than a recurring snapshot of one existing insight/dashboard, or a single one-off report. Pick a prompt subscription when the value is the _analysis itself_ (the LLM deciding what to query and writing it up), not a fixed chart they already built. For an insight/dashboard subscription, set `insight`/`dashboard` instead of `prompt` and the AI gates below don't apply.

> **Prefer a dashboard or insight subscription first.** A prompt subscription is the > heaviest option, and the LLM composes its own HogQL, so its numbers can drift from > what a saved insight or dashboard already shows. Reach for it only when (a) the user > **specifically asks** for a free-text / AI-written report, or (b) no existing insight > or dashboard covers the ask and the value really is the analysis itself. If the user > wants the key numbers from an **existing dashboard or insight** delivered on a > schedule — even phrased as "set up a scout/bot to post this daily" — a > **dashboard (or insight) subscription with `summary_enabled: true`** is usually the > better fit. Respect a user who's sure they want a prompt subscription, but when it's > ambiguous, suggest that and confirm first. See `managing-subscriptions` for the happy > path.

This skill covers **creating** the subscription. Once it exists you manage its lifecycle with the same `subscriptions-*` tools (see below): list it, edit/disable/ re-enable it, send a test delivery, or delete it.

Tools

| Tool | Purpose | | -------------------------------------------- | --------------------------------------------------- | | `posthog:subscriptions-create` | Create the recurring prompt subscription | | `posthog:subscriptions-list` | Confirm it landed; inspect existing subscriptions | | `posthog:subscriptions-partial-update` | Edit, disable (`enabled: false`), or re-enable it | | `posthog:subscriptions-test-delivery-create` | Send an immediate test delivery to its target(s) | | `posthog:subscriptions-delete` | Soft-delete it (stops all future deliveries) | | `posthog:integrations-list` | Find a Slack `integration_id` (filter `kind=slack`) | | `posthog:integrations-channels-retrieve` | List a Slack integration's channels (id + name) |

What you need before calling

The endpoint enforces three create-time gates and will return 400 if any fails:

1. **PostHog Cloud, or `DEBUG=true`** — self-hosted production deployments are not eligible (the LLM call routes through a PostHog-managed key). 2. **Org-level "AI data processing approved"** — must be toggled on in `Org settings → Data → AI data processing`. The user must opt in to AI features for the organization first. 3. **Prompt subscriptions enabled** for the organization — a PostHog-managed rollout flag. If it's off, the org has not been granted access yet; tell the user to reach out to PostHog to enable it (there is no self-serve toggle).

If any of the three is missing, stop and tell the user which one to fix — re-calling the tool will not help.

Your access token also needs the **`query:read`** scope in addition to `subscription:write`: a prompt subscription runs LLM-generated HogQL over the project's data, so the backend requires query access to create, edit/re-enable, test-deliver, or delete one. A `subscription:write`-only token is rejected with a 403.

Required arguments

prompt: "..."                         # ≤4000 chars; setting this (with no insight/dashboard) makes it a prompt sub → resource_type "ai_prompt"
target_type: "email" | "slack" | "teams"  # the only delivery channels the API accepts
target_value: "..."                   # comma-separated emails, "<channel_id>|<channel_name>", or a Microsoft Teams webhook URL
frequency: "daily" | "weekly" | "monthly" | "yearly"
interval: 1                            # 1 = every tick; 2 = every other tick; etc.
start_date: "2026-09-15T09:30:00Z"   # anchors the recurrence + time-of-day; hour and half-hour slots are supported; need not be in the future
title: "..."                          # display name in the subscriptions list
send_test_now: false                   # set true only after the user approves an immediate delivery

There is no `resource_type` argument to send — the kind is **derived** from which field you set (`prompt` ⇒ AI report) and returned as the read-only `resource_type`.

Optional arguments

byweekday: ['monday', 'wednesday'] # weekly only — days the rr