: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
/**
* Auto-generated from the Django backend OpenAPI schema.
* MCP service uses these Zod schemas for generated tool handlers.
* To regenerate: hogli build:openapi
*
* PostHog API - MCP 9 enabled ops
* OpenAPI spec version: 1.0.0
*/
import * as zod from 'zod'
/**
* Counts of $autocapture, $rageclick, and $dead_click events grouped by the element chain
* they occurred on, ordered by count. Defaults to all three event types; narrow with the
* include parameter.
*/
export const ElementsStatsRetrieveParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const ElementsStatsRetrieveQueryParams = () => zod.object({
data_attributes: zod
.string()
.optional()
.describe(
"Comma-separated data attribute names (wildcards allowed, e.g. data-\*). When provided, each element's attributes map is filtered to matching attr__\* keys, shrinking the response."
),
date_from: zod
.string()
.optional()
.describe('Start of the date range (e.g. -7d, 2024-01-01). Defaults to last 7 days.'),
date_to: zod.string().optional().describe('End of the date range (e.g. 2024-01-31). Defaults to now.'),
filter_test_accounts: zod
.boolean()
.optional()
.describe(
"When true, applies the project's internal-and-test-account filters to the underlying events. Pass the lowercase string true; other truthy spellings are ignored."
),
include: zod
.array(zod.string())
.optional()
.describe(
'Event types to include: $autocapture, $rageclick, $dead_click. Defaults to all three. Accepts repeated parameters, a JSON array, or a comma-separated list.'
),
limit: zod.number().optional().describe('Maximum rows per page'),
offset: zod.number().optional().describe('Pagination offset'),
properties: zod
.string()
.optional()
.describe(
'JSON-encoded list of property filters to apply to the underlying events, e.g. [{\"key\": \"$current_url\", \"value\": \"https:\/\/example.com\/page\"}] or [{\"key\": \"email\", \"value\": \"@posthog.com\", \"operator\": \"icontains\", \"type\": \"person\"}]. Supports event, person, cohort, element, and HogQL property filter types.'
),
sampling_factor: zod.number().optional().describe('Sampling factor between 0 and 1'),
})
export const InsightsListParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const insightsListQueryRefreshDefault = `force_cache`
export const InsightsListQueryParams = () => zod.object({
basic: zod.boolean().optional().describe('Return basic insight metadata only (no results, faster).'),
created_by: zod
.string()
.optional()
.describe(
'JSON-encoded array of user IDs. Only returns insights whose `created_by` is in the list, e.g. `[1,42]`.'
),
created_date_from: zod
.string()
.optional()
.describe('Filter by `created_at > created_date_from`. Accepts absolute or relative dates.'),
created_date_to: zod
.string()
.optional()
.describe('Filter by `created_at < created_date_to`. Accepts absolute or relative dates.'),
dashboards: zod
.string()
.optional()
.describe('JSON-encoded array of dashboard IDs. Returns insights attached to every listed dashboard (AND).'),
date_from: zod
.string()
.optional()
.describe(
'Filter by `last_modified_at > date_from`. Accepts absolute dates (`2025-04-23`) or relative strings (`-7d`, `-1m`).'
),
date_to: zod
.string()
.optional()
.describe('Filter by `last_modified_at < date_to`. Accepts absolute dates or relative strings.'),
display: zod
.string()
.optional()
.describe(
'Comma-separated chart types, e.g. `ActionsLineGraph,ActionsBar`. Only returns trends and SQL insights shown as one of them. A trends insight with no chart type set counts as `ActionsLineGraph`.'
),
exclude_bi: zod.boolean().optional().describe('Exclude Business intelligence worksheets from the insight list.'),
favorited: zod
.boolean()
.optional()
.describe('Include this parameter (any value) to restrict results to insights marked as favorited.'),
format: zod.enum(['csv', 'json']).optional(),
include_dashboards: zod
.boolean()
.optional()
.describe(
'Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead.'
),
insight: zod
.enum(['BI', 'FUNNELS', 'JOURNEYS', 'JSON', 'LIFECYCLE', 'PATHS', 'RETENTION', 'SQL', 'STICKINESS', 'TRENDS'])
.optional()
.describe(
'Restrict to a single insight type. `JSON` matches non-wrapper query insights; `SQL` matches HogQL queries; `BI` matches editable worksheets.'
),
last_viewed_date_from: zod
.string()
.optional()
.describe('Filter by `last_viewed_at > last_viewed_date_from`. Accepts absolute or relative dates.'),
last_viewed_date_to: zod
.string()
.optional()
.describe('Filter by `last_viewed_at < last_viewed_date_to`. Accepts absolute or relative dates.'),
limit: zod.number().optional().describe('Number of results to return per page.'),
offset: zod.number().optional().describe('The initial index from which to return the results.'),
order: zod
.string()
.optional()
.describe(
'Sort by an insight field, with a leading minus for descending order. Supports last_modified_at and last_viewed_at.'
),
refresh: zod
.enum([
'async',
'async_except_on_cache_miss',
'blocking',
'force_async',
'force_blocking',
'force_cache',
'lazy_async',
])
.default(insightsListQueryRefreshDefault)
.describe(
"\nWhether to refresh the retrieved insights, how aggressively, and if sync or async:\n- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates\n- `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache\n- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache\n- `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache\n- `'force_blocking'` - calculate synchronously, even if fresh results are already cached\n- `'force_async'` - kick off background calculation, even if fresh results are already cached\nBackground calculation can be tracked using the `query_status` response field."
),
saved: zod
.boolean()
.optional()
.describe(
'When truthy, restricts results to insights that are saved (or attached to a visible dashboard). When falsy, only unsaved insights.'
),
search: zod
.string()
.optional()
.describe(
"Search term matched across name, derived_name, description, and tag names. Returns exact (case-insensitive substring) matches only; if no exact match exists, returns similar (fuzzy trigram) matches instead. Each result's `search_match_type` is `exact` or `similar`."
),
short_id: zod.string().optional(),
tags: zod
.string()
.optional()
.describe('JSON-encoded array of tag names. Returns insights with any of the listed tags.'),
user: zod
.boolean()
.optional()
.describe(
'Include this parameter (any value) to restrict results to insights created by the authenticated user.'
),
})
export const InsightsCreateParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const InsightsCreateQueryParams = () => zod.object({
format: zod.enum(['csv', 'json']).optional(),
include_dashboards: zod
.boolean()
.optional()
.describe(
'Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead.'
),
})
export const insightsCreateBodyNameMax = 400
export const insightsCreateBodyDerivedNameMax = 400
export const insightsCreateBodyOrderMin = -2147483648
export const insightsCreateBodyOrderMax = 2147483647
export const insightsCreateBodyDescriptionMax = 400
export const InsightsCreateBody = () => zod
.object({
name: zod.string().max(insightsCreateBodyNameMax).nullish(),
derived_name: zod.string().max(insightsCreateBodyDerivedNameMax).nullish(),
order: zod.number().min(insightsCreateBodyOrderMin).max(insightsCreateBodyOrderMax).nullish(),
deleted: zod.boolean().optional(),
dashboards: zod
.array(zod.number())
.optional()
.describe(
'\n DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.\n A dashboard ID for each of the dashboards that this insight is displayed on.\n This field is omitted from session-authenticated responses unless `include_dashboards=true`\n is passed. Once opt-in enforcement is enabled, API-token callers (personal API keys, OAuth)\n must opt in the same way. Do not rely on it being present.\n '
),
description: zod.string().max(insightsCreateBodyDescriptionMax).nullish(),
tags: zod.array(zod.unknown()).optional(),
favorited: zod.boolean().optional(),
_create_in_folder: zod.string().optional(),
})
.describe('Simplified serializer to speed response times when loading large amounts of objects.')
export const InsightsRetrieveParams = () => zod.object({
id: zod
.union([zod.number(), zod.string()])
.describe('Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const insightsRetrieveQueryRefreshDefault = `force_cache`
export const InsightsRetrieveQueryParams = () => zod.object({
filters_override: zod
.string()
.optional()
.describe(
"Object (or pre-encoded JSON string) to override the insight's filters for this request only (not persisted). Top-level keys replace; nested values are not deep-merged — pass the complete value for any key you override. Accepts the same keys as the dashboard filters schema (e.g., `date_from`, `date_to`, `properties`). Ignored when accessed via a sharing token."
),
format: zod.enum(['csv', 'json']).optional(),
from_dashboard: zod
.number()
.optional()
.describe(
"\nOnly if loading an insight in the context of a dashboard: The relevant dashboard's ID.\nWhen set, the specified dashboard's filters and date range override will be applied."
),
include_dashboards: zod
.boolean()
.optional()
.describe(
'Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead.'
),
refresh: zod
.enum([
'async',
'async_except_on_cache_miss',
'blocking',
'force_async',
'force_blocking',
'force_cache',
'lazy_async',
])
.default(insightsRetrieveQueryRefreshDefault)
.describe(
"\nWhether to refresh the insight, how aggresively, and if sync or async:\n- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates\n- `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache\n- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache\n- `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache\n- `'force_blocking'` - calculate synchronously, even if fresh results are already cached\n- `'force_async'` - kick off background calculation, even if fresh results are already cached\nBackground calculation can be tracked using the `query_status` response field."
),
variables_override: zod
.string()
.optional()
.describe(
'Object (or pre-encoded JSON string) to override the insight\'s HogQL variables for this request only (not persisted). Format: {\"<variable_id>\": {\"code_name\": \"<code_name>\", \"variableId\": \"<variable_id>\", \"value\": <new_value>}}. Each entry must include `code_name` — partial entries are silently dropped. The simplest workflow is to call `insight-get` first, copy the matching entry from the response, and mutate `value`. Top-level keys replace; nested values are not deep-merged. Ignored when accessed via a sharing token.'
),
})
export const InsightsPartialUpdateParams = () => zod.object({
id: zod
.union([zod.number(), zod.string()])
.describe('Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const InsightsPartialUpdateQueryParams = () => zod.object({
format: zod.enum(['csv', 'json']).optional(),
include_dashboards: zod
.boolean()
.optional()
.describe(
'Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead.'
),
})
export const insightsPartialUpdateBodyNameMax = 400
export const insightsPartialUpdateBodyDerivedNameMax = 400
export const insightsPartialUpdateBodyOrderMin = -2147483648
export const insightsPartialUpdateBodyOrderMax = 2147483647
export const insightsPartialUpdateBodyDescriptionMax = 400
export const InsightsPartialUpdateBody = () => zod
.object({
name: zod.string().max(insightsPartialUpdateBodyNameMax).nullish(),
derived_name: zod.string().max(insightsPartialUpdateBodyDerivedNameMax).nullish(),
order: zod.number().min(insightsPartialUpdateBodyOrderMin).max(insightsPartialUpdateBodyOrderMax).nullish(),
deleted: zod.boolean().optional(),
dashboards: zod
.array(zod.number())
.optional()
.describe(
'\n DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.\n A dashboard ID for each of the dashboards that this insight is displayed on.\n This field is omitted from session-authenticated responses unless `include_dashboards=true`\n is passed. Once opt-in enforcement is enabled, API-token callers (personal API keys, OAuth)\n must opt in the same way. Do not rely on it being present.\n '
),
description: zod.string().max(insightsPartialUpdateBodyDescriptionMax).nullish(),
tags: zod.array(zod.unknown()).optional(),
favorited: zod.boolean().optional(),
_create_in_folder: zod.string().optional(),
})
.describe('Simplified serializer to speed response times when loading large amounts of objects.')
/**
* Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
*/
export const InsightsDestroyParams = () => zod.object({
id: zod
.union([zod.number(), zod.string()])
.describe('Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const InsightsDestroyQueryParams = () => zod.object({
format: zod.enum(['csv', 'json']).optional(),
})
/**
* Audit trail for a single insight — every change made to it, by whom, and when. Use this when you want the change history of a specific insight; use the project-wide activity endpoint for a broader view.
*/
export const InsightsActivityRetrieveParams = () => zod.object({
id: zod.number().describe('A unique integer value identifying this insight.'),
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const InsightsActivityRetrieveQueryParams = () => zod.object({
format: zod.enum(['csv', 'json']).optional(),
limit: zod.number().optional().describe('Page size. Defaults to 10.'),
page: zod.number().optional().describe('1-indexed page number. Defaults to 1.'),
})
/**
* Project-wide audit trail across all insights — who created, edited, deleted, or restored insights, what changed (with before/after diffs), and when. Useful for surfacing what people (or agents) have been working on recently.
*/
export const InsightsAllActivityRetrieveParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const InsightsAllActivityRetrieveQueryParams = () => zod.object({
format: zod.enum(['csv', 'json']).optional(),
limit: zod.number().optional().describe('Page size. Defaults to 10.'),
page: zod.number().optional().describe('1-indexed page number. Defaults to 1.'),
})
/**
* Returns insights ranked by view count over the last N days (default 7), highest first. Each result includes the same metadata as the standard insights list, plus a `view_count` and up to 3 recent `viewers`. Useful for surfacing the most-used insights in a project.
*/
export const InsightsTrendingRetrieveParams = () => zod.object({
project_id: zod
.string()
.describe(
"Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
),
})
export const InsightsTrendingRetrieveQueryParams = () => zod.object({
days: zod
.number()
.optional()
.describe(
"Time window in days to compute view counts over. Defaults to 7. Larger windows surface consistently popular insights; smaller windows surface what's hot right now."
),
format: zod.enum(['csv', 'json']).optional(),
include_dashboards: zod
.boolean()
.optional()
.describe(
'Opt in to receiving the deprecated `dashboards` field in insight payloads. Once opt-in enforcement is enabled, API-token callers stop receiving it by default; use `dashboard_tiles` instead.'
),
limit: zod.number().optional().describe('Maximum number of insights to return. Defaults to 10. Capped at 100.'),
offset: zod.number().optional().describe('The initial index from which to return the results.'),
})