:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
# MCP tool definitions. Tools are opt-in: an operation is exposed only when it has an entry here.
# List operations without an entry: pnpm --filter=@posthog/mcp run scaffold-yaml -- --candidates --product subscriptions
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product subscriptions
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
category: Subscriptions
feature: subscriptions
url_prefix: /subscriptions
ui_apps: {}
tools:
subscriptions-create:
operation: subscriptions_create
enabled: true
scopes:
- subscription:write
annotations:
readOnly: false
destructive: false
idempotent: false
title: Create subscription
description: >
Create a recurring subscription. The kind is inferred from which field you populate and returned as the
read-only `resource_type`:
(1) set `insight` — schedule periodic snapshots of one insight (`resource_type: "insight"`).
(2) set `dashboard` and `dashboard_export_insights` (the subset of the dashboard's insights to include, max
20) — schedule periodic snapshots of one dashboard (`resource_type: "dashboard"`).
(3) set `prompt` (≤4000 chars, with no insight or dashboard) — schedule a recurring LLM-generated report
(`resource_type: "ai_prompt"`). Available on PostHog Cloud (self-hosted production is not eligible) once the
organization has approved AI data processing and prompt subscriptions are enabled for it; otherwise create
is rejected with a 400. Creating a prompt subscription also requires the `query:read` scope — the report
runs LLM-generated HogQL over your data — so a `subscription:write`-only token is rejected for this kind.
Delivery is set by `target_type` — `email`, `slack`, or `teams` (a Microsoft Teams webhook URL in
`target_value`). A Teams webhook URL is only ever read back as its host. Creating a Teams subscription
requires the full webhook URL in `target_value`.
Set `start_date` to an ISO 8601 datetime. Its date anchors the recurrence and may be in the past. Deliveries
run on half-hour cycles at :00 and :30. Other minute values are accepted for backward compatibility, but
delivery happens during the next cycle instead of at that exact minute. For example, use a value ending in
`T16:30:00Z` for the 16:30 delivery cycle.
The kind is fixed at create time — a PATCH that would change the populated relation to a different kind is
rejected.
For insight and dashboard subscriptions you can attach an AI-generated summary to each delivery by setting
`summary_enabled: true` (optionally steered by `summary_prompt_guide`, which must be 500 characters or
fewer). This requires the organization to have approved AI data processing and to be within its
active-summary cap and AI credit budget; otherwise the create is rejected. Prompt subscriptions are
themselves AI-generated, so these fields do not apply to them.
`delivery_config` is optional, and every option in it applies to one subscription kind or delivery target
only. Omit the whole field unless the user asks for one of its options, because the create is rejected when
an option does not apply. Each option's own description says where it applies. None of them control the AI
summary on an insight or dashboard subscription, so use `summary_enabled` and `summary_prompt_guide` for
that instead.
IMPORTANT — when creating an insight (or dashboard) subscription, always ask the user whether to enable the
AI-generated summary before creating it. Present it as their choice: they can turn it on (`summary_enabled:
true`) or leave it off, and if they turn it on, offer them the option to add a custom prompt to steer the
summary (`summary_prompt_guide`). Do not enable the summary on your own without asking. (Prompt
subscriptions are themselves AI-generated, so this does not apply to them.)
exclude_params:
- contexts
- deleted
- next_delivery_date
- resource_name
- insight_short_id
- invite_message
subscriptions-delete:
operation: subscriptions_destroy
enabled: true
scopes:
- subscription:write
annotations:
readOnly: false
destructive: true
idempotent: true
title: Delete subscription
description: >
Soft-delete a subscription. Stops all future deliveries and returns the subscription with `deleted: true`.
One-way via MCP — there is no restore tool, so re-create the subscription if you need it back. Deleting an
prompt subscription additionally requires the `query:read` scope (the backend gates every write touching a
prompt subscription on query access).
param_overrides:
id:
cast: string-int
soft_delete: true
response:
exclude:
- invite_message
subscriptions-deliveries-list:
operation: subscriptions_deliveries_list
enabled: true
scopes:
- subscription:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: List subscription deliveries
description: >
List delivery history for a subscription — one row per send attempt. Each entry includes status (starting,
completed, failed, skipped), trigger_type (scheduled, manual, target_change), and timestamps (created_at,
finished_at). Filter with status=failed to quickly surface failed deliveries. Results are cursor-paginated
newest first. content_snapshot, recipient_results, and error are excluded to avoid leaking recipient
identifiers or upstream response bodies that may contain tokens / PII. ai_report (the full report markdown),
ai_report_prompt (the prompt it was generated from), and ai_report_diagnostics (per-query debug detail) are
also excluded here to keep list responses small — fetch a single delivery with
subscriptions-deliveries-retrieve to read the report and its prompt.
response:
exclude:
- content_snapshot
- recipient_results
- error
- ai_report
- ai_report_prompt
- ai_report_diagnostics
subscriptions-deliveries-retrieve:
operation: subscriptions_deliveries_retrieve
enabled: true
scopes:
- subscription:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get subscription delivery
description: >
Fetch a single subscription delivery attempt by id. Returns status, trigger_type, target_type, target_value,
timestamps, workflow/idempotency metadata, and exported_asset_ids. content_snapshot (the frozen
dashboard/insight state at send time) is not returned — use the insight/dashboard tools for current state.
recipient_results and error are also excluded to avoid leaking recipient identifiers or upstream response
bodies that may contain tokens / PII. Unlike the list tool, ai_report (the full report markdown for
AI-prompt subscriptions) is returned here, alongside ai_report_prompt (the prompt it was generated from).
ai_report_diagnostics (per-query generated HogQL + failure types) is excluded to keep the response focused
on the report itself.
response:
exclude:
- content_snapshot
- recipient_results
- error
- ai_report_diagnostics
subscriptions-list:
operation: subscriptions_list
enabled: true
scopes:
- subscription:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{id}'
list: true
title: List subscriptions
description: >
List the team's subscriptions. Use `search` to filter by title, insight name (including the auto-generated
name of an unnamed insight), dashboard name, or prompt text. Prompt subscriptions match both their `title`
and `prompt` text.
response:
exclude:
- invite_message
subscriptions-partial-update:
operation: subscriptions_partial_update
enabled: true
scopes:
- subscription:write
annotations:
readOnly: false
destructive: false
idempotent: true
title: Update subscription
description: >
Update a subscription's mutable fields (title, target, schedule, the `prompt` for prompt subscriptions,
`enabled`). The kind (`resource_type`) is fixed at create — a PATCH that would introduce another kind's
field (e.g. a `prompt` on an insight sub) is rejected with 400. For prompt subs, re-enabling a previously
auto-disabled sub requires both a valid `prompt` (already persisted or supplied in the PATCH body) and that
the original creator is still an active user; otherwise it is rejected with 400. Editing or re-enabling a
prompt subscription additionally requires the `query:read` scope. Use `subscriptions-delete` to soft-delete
— `deleted` is not settable here.
For Microsoft Teams, omit `target_value` to keep the stored webhook URL. To replace it, send a full Teams
webhook URL; the host returned by this API is not a valid replacement.
For insight and dashboard subscriptions, toggle the per-delivery AI summary with `summary_enabled` and steer
it with `summary_prompt_guide` (500 characters or fewer). Enabling a summary requires the organization to
have approved AI data processing and to be within its active-summary cap and AI credit budget; otherwise the
update is rejected.
`delivery_config` options carry the same scope rules as on create, and the update is rejected when an option
you send does not apply to this subscription. On a prompt subscription the object you send merges into the
stored one instead of replacing it, so set an option to the value you want rather than expecting an omitted
option to be cleared.
exclude_params:
- contexts
- deleted
- next_delivery_date
- resource_name
- insight_short_id
- invite_message
- send_test_now
subscriptions-retrieve:
operation: subscriptions_retrieve
enabled: true
scopes:
- subscription:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get subscription
description:
'Fetch a single subscription by numeric ID. Returns its kind (`resource_type`: insight, dashboard, or
ai_prompt), target (`target_type`/`target_value`, host-only for a Teams webhook), schedule, enabled state,
and AI-summary settings. Metadata only — for the send history and delivered reports, use
`subscriptions-deliveries-list` / `subscriptions-deliveries-retrieve`.'
response:
exclude:
- invite_message
subscriptions-summaries-list:
operation: subscriptions_summaries_list
enabled: true
scopes:
- subscription:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: List AI summaries for an insight or dashboard
description: >
List the AI summaries that subscriptions sent for one insight or dashboard, newest first. Set exactly one of
`insight` or `dashboard` (numeric ID). Each row comes from a completed delivery and includes the summary
text, the subscription ID and title, the channel, and the covered period from `period_start` to
`created_at`. `period_start` is null for the first delivery of a subscription. Summaries from deleted
subscriptions are not returned. Use subscriptions-partial-update with `summary_prompt_guide` to change how
future summaries of one subscription are written. Results are cursor-paginated.
feature_flag: subscription-source-summaries
subscriptions-test-delivery-create:
operation: subscriptions_test_delivery_create
enabled: true
scopes:
- subscription:write
annotations:
readOnly: false
destructive: false
idempotent: false
title: Send test delivery
description: >
Trigger an immediate test delivery of a subscription to its configured target(s) (email, Slack, or Microsoft
Teams). Runs the same pipeline as a scheduled delivery but with trigger_type=manual, producing a real
delivery record you can inspect via subscriptions-deliveries-list / subscriptions-deliveries-retrieve.
Returns 202 Accepted once the delivery workflow is queued; poll subscriptions-deliveries-list (newest first)
or subscriptions-deliveries-retrieve for the outcome. Returns 409 if a test delivery for the same
subscription is already in flight, or if the subscription is disabled (re-enable it first); 404 if it has
been deleted. Test-delivering a prompt subscription additionally requires the `query:read` scope (it runs
the AI HogQL pipeline).