PostHog
OfficialQuery analytics, manage feature flags, run experiments, and track errors.
Tools (172)
docs-search
Use this tool to search the PostHog documentation for information that can help the user with their request. Use it as a fallback when you cannot answer the user's request using other tools in this MCP. Only use this tool for PostHog related questions.
experiment-get-all
Get all experiments in the project.
experiment-create
Create a comprehensive A/B test experiment. PROCESS: 1) Understand experiment goal and hypothesis 2) Search existing feature flags with 'feature-flags-get-all' tool first and suggest reuse or new key 3) Help user define success metrics by asking what they want to optimize 4) MOST IMPORTANT: Use 'event-definitions-list' tool to find available events in their project 5) For funnel metrics, ask for specific event sequence (e.g., ['product_view', 'add_to_cart', 'purchase']) and use funnel_steps parameter 6) Configure variants (default 50/50 control/test unless they specify otherwise) 7) Set targeting criteria if needed.
experiment-delete
Delete an experiment by ID.
experiment-update
Update an existing experiment by ID. Can update name, description, lifecycle state, variants, metrics, and other properties. RESTART WORKFLOW: To restart a concluded experiment, set end_date=null, conclusion=null, conclusion_comment=null, and optionally set a new start_date. To make it draft again, also set start_date=null. COMMON PATTERNS: Launch draft (set start_date), stop running (set end_date + conclusion), archive (set archived=true), modify variants (update parameters.feature_flag_variants). NOTE: feature_flag_key cannot be changed after creation.
experiment-get
Get details of a specific experiment by ID.
experiment-results-get
Get comprehensive experiment results including all metrics data (primary and secondary) and exposure data. This tool fetches the experiment details and executes the necessary queries to get complete experiment results. Only works with new experiments (not legacy experiments).
insight-create-from-query
Create an insight from a query that you have previously tested with 'query-run'. You should check the query runs, before creating an insight. Do not create an insight before running the query, unless you know already that it is correct (e.g. you are making a minor modification to an existing query you have seen).
insight-delete
Delete an insight by ID (soft delete - marks as deleted).
insight-get
Get a specific insight by ID.
insight-query
Execute a query on an existing insight to get its results/data. Provide the insight ID to retrieve the current query results.
insights-get-all
Get all insights in the project with optional filtering. Can filter by saved status, favorited status, or search term.
insight-update
Update an existing insight by ID. Can update name, description, filters, and other properties. You should get the insight before update it to see it's current query structure, and only modify the parts needed to answer the user's request.
query-run
You should use this to answer questions that a user has about their data and for when you want to create a new insight. You can use 'event-definitions-list' to get events to use in the query, and 'event-properties-list' to get properties for those events. It can run a trend, funnel, paths or HogQL query. Where possible, use a trend, funnel or paths query rather than a HogQL query, unless you know the HogQL is correct (e.g. it came from a previous insight.). Use PathsQuery to visualize user flows and navigation patterns — set includeEventTypes to ['hogql'] with a pathsHogQLExpression for custom path steps.
query-generate-hogql-from-question
This is a slow tool, and you should only use it once you have tried to create a query using the 'query-run' tool, or the query is too complicated to create a trend / funnel. Queries project's PostHog data based on a provided natural language question - don't provide SQL query as input but describe the output you want. When giving the results back to the user, first show the SQL query that was used, then provide results in easily readable format. You should also offer to save the query as an insight if the user wants to.
evaluations-get
List LLM analytics evaluations for the project. Evaluations automatically score AI generations for quality, relevance, safety, and other criteria. Supports optional search by name/description and filtering by enabled status. Evaluation results are stored as '$ai_evaluation' events — to query results, use the execute-sql or query-run tool with a HogQL query filtering on event = '$ai_evaluation'. Key properties: $ai_evaluation_id (evaluation UUID), $ai_evaluation_name, $ai_target_event_id (generation event UUID), $ai_trace_id, $ai_evaluation_result (boolean pass/fail), $ai_evaluation_reasoning (text), $ai_evaluation_applicable (boolean, false = N/A).
evaluation-get
Get a specific LLM analytics evaluation by its UUID. Returns full details including name, type (llm_judge or hog), configuration, conditions, and enabled status.
evaluation-create
Create a new LLM analytics evaluation. Two types are supported: 'llm_judge' uses an LLM to score generations against a prompt you define (for subjective checks like tone, helpfulness, hallucination detection), and 'hog' runs deterministic code against each generation (for rule-based checks like format validation, keyword detection, length limits). For llm_judge evaluations, provide a prompt in evaluation_config and a model_configuration. For hog evaluations, provide source code in evaluation_config.
evaluation-update
Update an existing LLM analytics evaluation. You can change the name, description, enabled status, evaluation config (prompt or source code), and output config. Use this to enable/disable evaluations or modify their scoring logic.
evaluation-delete
Delete an LLM analytics evaluation (soft delete). The evaluation will be marked as deleted and will no longer run.
evaluation-run
Trigger an evaluation run on a specific $ai_generation event. This executes the evaluation (either LLM judge or Hog code) against the target event asynchronously via a background workflow. The run is async — it returns a workflow_id and status 'started'. Results are written as '$ai_evaluation' events once complete. To check results after triggering a run, query events with: SELECT properties.$ai_evaluation_result as result, properties.$ai_evaluation_reasoning as reasoning FROM events WHERE event = '$ai_evaluation' AND properties.$ai_evaluation_id = '<evaluation_uuid>' AND properties.$ai_target_event_id = '<generation_event_uuid>' ORDER BY timestamp DESC LIMIT 1.
evaluation-test-hog
Test Hog evaluation code against recent $ai_generation events without persisting results. Compiles the provided Hog source code and runs it against a sample of recent events (up to 10 from the last 7 days). Returns per-event results with input/output previews, pass/fail verdicts, and any errors. Use this to validate Hog evaluation logic before enabling it.
get-llm-total-costs-for-project
Fetches the total LLM daily costs for each model for a project over a given number of days. If no number of days is provided, it defaults to 7. The results are sorted by model name. The total cost is rounded to 4 decimal places. The query is executed against the project's data warehouse. Show the results as a Markdown formatted table with the following information for each model: Model name, Total cost in USD, Each day's date, Each day's cost in USD. Write in bold the model name with the highest total cost. Properly render the markdown table in the response.
organization-details-get
Get the details of the active organization.
organizations-get
Get the organizations the user has access to.
switch-organization
Change the active organization from the default organization. You should only use this tool if the user asks you to change the organization - otherwise, the default organization will be used.
projects-get
Fetches projects that the user has access to in the current organization.
event-definitions-list
List all event definitions in the project with optional filtering. Can filter by search term.
event-definition-update
Update event definition metadata. Can update description, tags, mark status as verified or hidden. Use exact event name like '$pageview' or 'user_signed_up'.
properties-list
List properties for events or persons. If fetching event properties, you must provide an event name.
switch-project
Change the active project from the default project. You should only use this tool if the user asks you to change the project - otherwise, the default project will be used.
survey-create
Creates a new survey in the project. Surveys can be popover or API-based and support various question types including open-ended, multiple choice, rating, and link questions. Once created, you should ask the user if they want to add the survey to their application code.
survey-get
Get a specific survey by ID. Returns the survey configuration including questions, targeting, and scheduling details.
surveys-get-all
Get all surveys in the project with optional filtering. Can filter by search term or use pagination.
survey-update
Update an existing survey by ID. Can update name, description, questions, scheduling, and other survey properties.
survey-delete
Delete a survey by ID (soft delete - marks as archived).
surveys-global-stats
Get aggregated response statistics across all surveys in the project. Includes event counts (shown, dismissed, sent), unique respondents, conversion rates, and timing data. Supports optional date filtering.
survey-stats
Get response statistics for a specific survey. Includes detailed event counts (shown, dismissed, sent), unique respondents, conversion rates, and timing data. Supports optional date filtering.
entity-search
Search for PostHog entities by name or description. Can search across multiple entity types including insights, dashboards, experiments, feature flags, notebooks, actions, cohorts, event definitions, and surveys. Use this to find entities when you know part of their name. Returns matching entities with their IDs and URLs.
debug-mcp-ui-apps
Debug tool for testing MCP Apps SDK integration. Returns sample data displayed in an interactive UI app with component showcase. Use this to verify that MCP Apps are working correctly.
actions-get-all
Get all actions in the project. Actions are reusable event definitions that can combine multiple trigger conditions (page views, clicks, form submissions) into a single trackable event for use in insights and funnels. Supports pagination with limit and offset parameters. Note: Search/filtering by name is not supported on this endpoint.
action-create
Create a new action in the project. Actions define reusable event triggers based on page views, clicks, form submissions, or custom events. Each action can have multiple steps (OR conditions). Use actions to create composite events for insights and funnels. Example: Create a 'Sign Up Click' action with steps matching button clicks on the signup page.
action-get
Get a specific action by ID. Returns the action configuration including all steps and their trigger conditions.
action-update
Update an existing action by ID. Can update name, description, steps, tags, and Slack notification settings.
action-delete
Delete an action by ID (soft delete - marks as deleted). The action will no longer appear in lists but historical data is preserved.
activity-logs-list
List recent activity logs for the project. Shows who changed what and when — includes feature flag updates, insight creations, dashboard modifications, experiment launches, and other project changes. Use scope parameter to filter by resource type (e.g. "FeatureFlag", "Insight", "Dashboard", "Experiment", "Survey", "Cohort"). Use item_id to filter changes for a specific resource. Returns results ordered by most recent first. Each result includes: user (who performed the action with first_name and email), activity (e.g. "created", "updated", "deleted"), scope (entity type like "FeatureFlag"), item_id (ID of the affected resource), detail (structured JSON with name, short_id, and a changes array where each change has type, action, field, before, and after values), and created_at timestamp.
alerts-list
List all insight alerts in the project. Returns alerts with their current state, threshold or detector configuration, timing information, and firing check history. Supports filtering by insight ID via query parameter. Alerts can use either threshold-based conditions (absolute_value, relative_increase, relative_decrease) or anomaly detection via detector_config (zscore, mad, iqr, isolation_forest, knn, etc.).
alert-get
Get a specific alert by ID. Returns the full alert configuration including check results, threshold settings, detector_config (for anomaly detection alerts), and subscribed users. Check results include anomaly_scores, triggered_points, and triggered_dates for detector-based alerts. By default returns the last 5 checks. Use checks_date_from and checks_date_to (e.g. '-24h', '-7d') to get checks within a time window, and checks_limit to control the maximum returned (default 5, max 500). When date filters are provided without checks_limit, up to 500 checks are returned. Check history is retained for 14 days.
alert-create
Create a new alert on an insight. Alerts can use either threshold-based conditions or anomaly detection. For threshold alerts: set condition (absolute_value, relative_increase, relative_decrease) and threshold configuration with bounds. For anomaly detection: set detector_config with a detector type (zscore, mad, iqr, threshold, copod, ecod, hbos, isolation_forest, knn, lof, ocsvm, pca) and parameters like threshold (sensitivity 0-1, default 0.9) and window size. Ensemble detectors combine 2+ sub-detectors with AND/OR logic. Requires an insight ID and at least one subscribed user.
alert-update
Update an existing alert by ID. Can update name, threshold, condition, config, detector_config, subscribed users, enabled state, calculation interval, and weekend skipping. Set detector_config to switch to anomaly detection, or set it to null to switch back to threshold mode. To snooze an alert, set snoozed_until to a relative date string (e.g. '2h', '1d'). To unsnooze, set snoozed_until to null.
alert-delete
Delete an alert by ID. This permanently removes the alert and all its check history. Subscribed users will no longer receive notifications.
alert-simulate
Run an anomaly detector on an insight's historical data without creating any alert or check records. Use this to preview how a detector configuration would perform before saving it as an alert. Requires an insight ID and a detector_config object with a type (zscore, mad, iqr, copod, ecod, hbos, isolation_forest, knn, lof, ocsvm, pca, or ensemble). Optionally specify date_from (e.g. '-48h', '-30d') to control how far back to simulate, and series_index to pick which series to analyze. Returns data values, anomaly scores per point, triggered indices and dates, and for ensemble detectors, per-sub-detector score breakdowns.
annotations-list
List annotations in the current project, newest first. Use this to review existing deployment markers and analysis notes before adding new annotations.
annotation-create
Create an annotation to mark an important change (for example, a deployment) on charts and trends. Provide a note in `content`, when it happened in `date_marker` (ISO 8601), and whether it is scoped to the current `project` or the whole `organization`.
annotation-retrieve
Retrieve a single annotation by ID from the current project. Use this when you already know the annotation ID and want complete details.
annotations-partial-update
Update an existing annotation by ID. You can change its text (`content`), when it happened (`date_marker`, ISO 8601), or its visibility scope (`project` or `organization`). Only the fields you provide are updated.
annotation-delete
Soft-delete an annotation by ID. This hides the annotation from normal lists while preserving historical records.
cdp-function-templates-list
List available function templates. Templates are pre-built function configurations for common integrations (Slack, webhooks, email, etc.) and transformations (GeoIP, etc.). Filter by type (destination, site_destination, site_app, transformation, etc.) via the 'type' query parameter. Results are sorted by popularity (number of active functions using each template).
cdp-function-templates-retrieve
Get a specific function template by its template ID (e.g. 'template-slack', 'template-geoip'). Returns the full template including source code, inputs schema, default filters, and mapping templates. Use this to understand what inputs a template requires before creating a function from it.
cdp-functions-list
List all functions (destinations, transformations, site apps, and source webhooks) in the project. Returns each function's name, type, enabled status, execution order, and template info. Filter by type (destination, site_destination, internal_destination, source_webhook, warehouse_source_webhook, site_app, transformation) and enabled status via query parameters.
cdp-functions-create
Create a new function. Requires 'type' (destination, site_destination, internal_destination, source_webhook, warehouse_source_webhook, site_app, or transformation) and either 'hog' source code or a 'template_id' to derive code from a template. Provide 'inputs_schema' to define configurable parameters and 'inputs' with their values. Use 'filters' to control which events trigger the function. Transformations run during ingestion and have an 'execution_order' field.
cdp-functions-retrieve
Get a specific function by ID. Returns the full configuration including source code, inputs schema, input values (secrets are masked), filters, mappings, masking config, and runtime status.
cdp-functions-partial-update
Partially update a function. Can enable/disable the function, change its name, description, source code, inputs, filters, mappings, or masking config. The 'type' field cannot be changed after creation. To delete a function, use the cdp-functions-delete tool instead.
cdp-functions-delete
Delete a function by ID (soft delete). The function will no longer appear in lists or process events, but historical data is preserved.
cdp-functions-invocations-create
Test-invoke a function with a mock event payload. Sends the function configuration and test data to the plugin server for execution and returns logs and status. Use 'mock_async_functions: true' (default) to simulate external calls like fetch() without making real HTTP requests.
cdp-functions-rearrange-partial-update
Update the execution order of transformation functions. Send an 'orders' object mapping function UUIDs to their new execution_order integer values. Only applies to functions with type=transformation. Returns the updated list of transformations.
cohorts-list
List all cohorts in the project. Returns a summary of each cohort including id, name, description, count (person count), is_static (cohort type), and created_at timestamp. Use 'cohorts-retrieve' with the cohort ID to get full details including filters, calculation status, and query definition.
cohorts-create
Create a new cohort. For dynamic cohorts, provide 'filters' with AND/OR groups of property conditions (person properties, behavioral filters, or cohort references). For static cohorts, set 'is_static: true' then use the 'cohorts-add-persons-to-static-cohort-partial-update' tool to add person UUIDs.
cohorts-retrieve
Get a specific cohort by ID. Returns the cohort name, description, filters (for dynamic cohorts), count of matching users, and calculation status.
cohorts-partial-update
Update an existing cohort's name, description, or filters. Changing filters on a dynamic cohort triggers recalculation. To soft-delete a cohort, set 'deleted: true'.
cohorts-add-persons-to-static-cohort-partial-update
Add persons to a static cohort by their UUIDs. Only works for static cohorts (is_static: true).
cohorts-rm-person-from-static-cohort-partial-update
Remove a person from a static cohort by their UUID. Only works for static cohorts (is_static: true). The person must exist in the project. Idempotent: removing a person who exists but is not a member of the cohort succeeds silently.
dashboards-get-all
Get all dashboards in the project with optional filtering by pinned status or search term. Returns name, description, pinned status, tags, and creation metadata.
dashboard-create
Create a new dashboard. Provide a name and optional description, tags, and pinned status. Can also create from a template or duplicate an existing dashboard.
dashboard-get
Get a specific dashboard by ID. Returns the full dashboard including all tiles with their insights and layout information.
dashboard-update
Update an existing dashboard by ID. Can update name, description, pinned status, tags, filters, and restriction level.
dashboard-delete
Delete a dashboard by ID. The dashboard will be soft-deleted and no longer appear in lists.
dashboard-reorder-tiles
Reorder tiles on a dashboard by providing an array of tile IDs in the desired display order. Computes a 2-column grid layout (6 columns wide, 5 rows tall per tile). First, use dashboard-get to see current tile IDs.
view-list
List all data warehouse saved queries (views) in the project. Returns each view's name, materialization status, sync frequency, column schema, latest error, and last run timestamp. Use this to discover available views before querying them in HogQL.
view-create
Create a new data warehouse saved query (view). If a view with the same name already exists, it will be updated instead (upsert behavior). The query must be valid HogQL. After creation, the view can be referenced by name in other HogQL queries.
view-get
Get a specific data warehouse saved query (view) by ID. Returns the full view definition including the HogQL query, column schema, materialization status, sync frequency, and run history metadata.
view-update
Update an existing data warehouse saved query (view). Can change the name, HogQL query, or sync frequency. Changing the query triggers column re-inference and sets the status to 'modified'. Use sync_frequency to control materialization schedule: '24hour', '12hour', '6hour', '1hour', '30min', or 'never'. IMPORTANT: when updating the query field, you must first retrieve the view to get its latest_history_id, then pass that value as edited_history_id for conflict detection.
view-delete
Delete a data warehouse saved query (view) by ID. This is a soft delete — the view is marked as deleted and will no longer appear in lists or be queryable in HogQL. Any materialization schedule is also removed. Cannot delete views that have downstream dependencies or views from managed viewsets.
view-materialize
Enable materialization for a saved query. This creates a physical table from the view's query and sets up a 24-hour sync schedule to keep it refreshed. Materialized views are faster to query but use storage. Use 'view-unmaterialize' to undo. Rate limited.
view-unmaterialize
Undo materialization for a saved query. Deletes the materialized table and removes the sync schedule, reverting the view back to a virtual query that runs on each access. The view definition itself is preserved. Rate limited.
view-run
Trigger a manual materialization run for a saved query. This immediately refreshes the materialized table with the latest data. The view must already be materialized. Use 'view-run-history' to check run status.
view-run-history
Get the 5 most recent materialization run statuses for a saved query. Each entry includes the run status and timestamp. Use this to monitor whether materialization is running successfully.
early-access-feature-list
List early access features in the current project. Returns name, stage, description, linked feature flag, and creation date for each feature.
early-access-feature-create
Create a new early access feature. A feature flag is automatically created unless feature_flag_id is provided. Stage determines whether opted-in users get the feature enabled.
early-access-feature-retrieve
Get a single early access feature by ID. Returns full details including the linked feature flag configuration.
early-access-feature-partial-update
Update an early access feature by ID. Changing the stage automatically updates the linked feature flag's enrollment conditions.
early-access-feature-destroy
Delete an early access feature by ID. Clears enrollment conditions from the linked feature flag but does not delete the flag itself.
endpoints-get-all
Get all API endpoints in the current project. Endpoints expose saved HogQL or insight queries as callable API routes. Returns name, description, query, active status, current version, and materialization info for each endpoint.
endpoint-get
Get a specific endpoint by name. Returns the full endpoint configuration including query definition, version info, materialization status, and column types. Supports ?version=N to retrieve a specific version.
endpoint-create
Create a new API endpoint from a HogQL or insight query. The name must be URL-safe (letters, numbers, hyphens, underscores, starts with a letter, max 128 chars). Materialization is auto-enabled if the query is eligible.
endpoint-update
Update an existing endpoint by name. Can update the query (auto-creates a new version), description, cache age, active status, and materialization. Pass version in body to target a specific version for non-query updates.
endpoint-delete
Delete an endpoint by name. The endpoint is soft-deleted and its materialized views are cleaned up.
endpoint-run
Execute an endpoint's query and return results. Uses materialized results when available, otherwise runs inline. For HogQL endpoints, variable keys must match code_name values. For insight endpoints with breakdowns, use the breakdown property name as the key.
endpoint-versions
List all versions for an endpoint, in descending order (latest first). Each version contains the query snapshot, description, cache settings, and materialization status at that point in time.
endpoint-materialization-status
Get lightweight materialization status for an endpoint without fetching full endpoint data. Returns whether materialization is possible, current status, last run time, and any errors. Supports ?version=N.
endpoint-openapi-spec
Get the OpenAPI 3.0 specification for an endpoint. Returns a JSON spec that can be used with SDK generators like openapi-generator or @hey-api/openapi-ts to create typed API clients. Supports ?version=N to generate a spec for a specific version.
error-tracking-issues-list
List all error tracking issues in the project. Returns issues with status, volume, first/last seen timestamps, and assignee info.
error-tracking-issues-retrieve
Get a specific error tracking issue by ID. Returns full issue details including status, description, volume, and metadata.
error-tracking-issues-partial-update
Update an error tracking issue. Can change status (active, resolved, suppressed), assign to a user, or update description.
error-tracking-issues-merge-create
Merge one or more error tracking issues into an existing target issue. Provide the target issue as `id` and the issues to merge into it as `ids`.
query-error-tracking-issues
Query error tracking issues to find, filter, and inspect errors in the project. Returns aggregated metrics per issue including occurrence count, affected users, sessions, and volume data. Use 'read-data-schema' to discover available events, actions, and properties for filters. This is a unified query tool — use it both to list issues and to get details on a specific issue: - **List issues**: omit `issueId` to get a filtered, sorted list of error tracking issues. - **Get issue details**: provide `issueId` to get aggregated metrics for a single issue. Use `error-tracking-issues-retrieve` to get the full issue model (description, assignee, external references) and `error-tracking-issues-partial-update` to change status or assignee. CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization. # Data narrowing ## Property filters Use property filters via the `filterGroup` field to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional filtering and always use the minimum set of property filters needed. IMPORTANT: Do not check if a property is set unless the user explicitly asks for it. When using a property filter, you should: - **Prioritize properties directly related to the context or objective of the user's query.** Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like `$browser`, `$os`, or `$geoip_country_code`. - **Ensure that you find both the property group and name.** Property groups should be one of the following: event, person, session, group. - After selecting a property, **validate that the property value accurately reflects the intended criteria**. - **Find the suitable operator for type** (e.g., `contains`, `is set`). - If the operator requires a value, use the `read-data-schema` tool to find the property values. Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group. Supported operators for the String type are: - equals (exact) - doesn't equal (is_not) - contains (icontains) - doesn't contain (not_icontains) - matches regex (regex) - doesn't match regex (not_regex) - is set - is not set Supported operators for the Numeric type are: - equals (exact) - doesn't equal (is_not) - greater than (gt) - less than (lt) - is set - is not set Supported operators for the DateTime type are: - equals (is_date_exact) - doesn't equal (is_not for existence check) - before (is_date_before) - after (is_date_after) - is set - is not set Supported operators for the Boolean type are: - equals - doesn't equal - is set - is not set All operators take a single value except for `equals` and `doesn't equal` which can take one or more values (as an array). ## Time period You should not filter events by time using property filters. Instead, use the `dateRange` field. If the question doesn't mention time, the default is the last 7 days. # Parameters ## issueId (optional) When provided, returns aggregated metrics for a single error tracking issue. When omitted, returns a paginated list of issues matching the filters. ## status Filter by issue status. Available values: `active`, `resolved`, `suppressed`, `pending_release`, `archived`, `all`. Defaults to `active`. ## orderBy Field to sort results by: `occurrences`, `last_seen`, `first_seen`, `users`, `sessions`. Defaults to `occurrences`. ## searchQuery Free-text search across exception type, message, and stack frames. Use this when the user is looking for a specific error by name or message content. ## assignee Filter issues by assignee. The value is a user ID. Use this when the user asks to see errors assigned to a specific person. ## filterGroup A flat list of property filters to narrow results. Each filter specifies a property key, operator, type (event/person/session/group), and value. See the "Property filters" section above for usage guidelines and supported operators. ## volumeResolution Controls the granularity of the volume chart data returned with each issue. Use `1` (default) for list views where you want a volume sparkline. Use `0` when you only need aggregate counts without volume data. ## dateRange Date range to filter results. Defaults to the last 7 days (`-7d`). - `date_from`: Start of the range. Accepts ISO 8601 timestamps (e.g., `2024-01-15T00:00:00Z`) or relative formats: `-7d`, `-2w`, `-1m`, `-1h`, `-1mStart`, `-1yStart`. - `date_to`: End of the range. Same format. Omit or null for "now". ## limit / offset Pagination controls. `limit` defaults to 50. # Examples ## List all active errors sorted by occurrence count ```json {} ``` All defaults apply: `status: "active"`, `orderBy: "occurrences"`, `dateRange: { "date_from": "-7d" }`. ## Search for a specific error ```json { "searchQuery": "TypeError: Cannot read property", "limit": 10 } ``` ## Get details for a specific issue ```json { "issueId": "01234567-89ab-cdef-0123-456789abcdef", "volumeResolution": 0 } ``` ## List resolved errors from the last 30 days ```json { "status": "resolved", "dateRange": { "date_from": "-30d" }, "orderBy": "last_seen" } ``` ## Find most recent errors ```json { "orderBy": "first_seen", "orderDirection": "DESC", "dateRange": { "date_from": "-24h" } } ``` ## Errors from Chrome users only ```json { "filterGroup": [{ "key": "$browser", "operator": "exact", "type": "event", "value": ["Chrome"] }] } ``` ## Errors from US users in the last 30 days ```json { "filterGroup": [{ "key": "$geoip_country_code", "operator": "exact", "type": "event", "value": ["US"] }], "dateRange": { "date_from": "-30d" } } ``` # Reminders - Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details. - Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.
feature-flag-get-all
Get feature flags in the current project. Supports list filters including search by feature flag key or name (case-insensitive), then use the returned ID for get/update/delete tools.
feature-flag-get-definition
Get a feature flag by ID.
create-feature-flag
Create a feature flag in the current project.
update-feature-flag
Update a feature flag by ID in the current project.
delete-feature-flag
Soft-delete a feature flag by ID in the current project.
feature-flags-activity-retrieve
Get the audit trail for a specific feature flag by ID. Returns a paginated list of changes including who made changes, what was changed, and when. Use limit and page query params for pagination.
feature-flags-dependent-flags-retrieve
Get other active feature flags that depend on this flag. Use this to understand flag dependency chains before making changes to a flag's rollout conditions or disabling it.
feature-flags-status-retrieve
Check the health and evaluation status of a feature flag by ID. Returns a status (active, stale, deleted, or unknown) and a human-readable reason explaining the status.
feature-flags-evaluation-reasons-retrieve
Debug why feature flags evaluate a certain way for a given user. Provide a distinct_id and optionally groups to see each flag's evaluated value and the reason for that evaluation (e.g. condition_match, no_condition_match, disabled).
feature-flags-user-blast-radius-create
Assess the impact of a feature flag release condition before applying it. Provide a condition object and optionally a group_type_index to see how many users would be affected relative to the total user count.
feature-flags-copy-flags-create
Copy a feature flag from one project to other projects within the same organization. Provide the flag key, source project ID, and a list of target project IDs. Optionally copy scheduled changes with copy_schedule. Returns lists of successful and failed copies.
scheduled-changes-list
List scheduled changes in the current project. Filter by model_name=FeatureFlag and record_id to see schedules for a specific flag. Returns pending, executed, and failed schedules with their payloads and timing. Use this to check what changes are queued for a feature flag before modifying it.
scheduled-changes-get
Get a single scheduled change by ID. Returns the full details including the payload, schedule timing, execution status, and any failure reason.
scheduled-changes-create
Schedule a future change to a feature flag. Supported operations: 'update_status' (enable/disable), 'add_release_condition', and 'update_variants'. Provide the flag ID as record_id, model_name as "FeatureFlag", a payload with the operation and value, and a scheduled_at datetime.
scheduled-changes-update
Update a pending scheduled change by ID. You can modify the payload, scheduled_at time, or recurrence settings. Cannot change the target record (record_id) or model type (model_name).
scheduled-changes-delete
Delete a scheduled change by ID. This permanently removes the scheduled change and it will not be executed.
integrations-list
List all third-party integrations configured in the current project. Returns each integration's type (kind), display name, non-sensitive configuration, error status, and creation metadata. Common kinds include slack, github, hubspot, salesforce, and various ad platforms. When authenticated via personal API key, only GitHub integrations are returned.
integration-get
Get a specific integration by ID. Returns the full integration details including kind, display name, non-sensitive configuration, error status, and creation metadata. Does not expose sensitive credentials.
integration-delete
Permanently delete an integration by ID. This removes the connection to the third-party service. Any features relying on this integration (alerts, workflow destinations, etc.) will stop working.
llm-analytics-clustering-jobs-list
List all clustering job configurations for the current team (max 5 per team). Each job defines an analysis level (trace or generation) and event filters that scope which traces are included in clustering runs. Cluster results are stored as $ai_trace_clusters and $ai_generation_clusters events — use docs-search or execute-sql to query them.
llm-analytics-evaluation-summary-create
Generate an AI-powered summary of LLM evaluation results for a given evaluation config. Pass an evaluation_id and an optional filter ("all", "pass", "fail", or "na") to scope which runs are analyzed. Returns an overall assessment, pattern groups for passing, failing, and N/A runs (each with title, description, frequency, and example generation IDs), actionable recommendations, and run statistics. Optionally pass generation_ids to restrict the analysis to specific runs. Results are cached for one hour — use force_refresh to recompute. Rate-limited; requires AI data processing approval for the organization.
llm-analytics-sentiment-create
Classify sentiment of LLM trace or generation user messages as positive, neutral, or negative. Pass a list of trace or generation IDs and an analysis_level ("trace" or "generation"). Returns per-ID sentiment labels with confidence scores and per-message breakdowns. Results are cached — use force_refresh to recompute. Rate-limited.
llm-analytics-summarization-create
Generate an AI-powered summary of an LLM trace or generation. Pass a trace_id or generation_id with a date_from — the backend fetches the data and returns a structured summary with title, flow diagram, summary bullets, and interesting notes. Results are cached. Use mode "minimal" (default) for 3-5 points or "detailed" for 5-10 points. Rate-limited.
llm-analytics-clustering-jobs-retrieve
Retrieve a specific clustering job configuration by ID. Returns the job name, analysis level (trace or generation), event filters, enabled status, and timestamps.
query-logs
Query log entries with filtering by severity, service name, date range, search term, and structured attribute filters. Supports cursor-based pagination. Returns log entries with timestamp, body, level, service_name, trace_id, and attributes. Use 'logs-list-attributes' and 'logs-list-attribute-values' to discover available attributes before building filters. CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization. All parameters must be nested inside a `query` object. # Data narrowing ## Property filters Use property filters via the `query.filterGroup` field to narrow results. Only include property filters when they are essential to directly answer the user's question. When using a property filter, you should: - **Choose the right type.** Log property types are: - `log` — filters the log body/message. Use key "message" for this type. - `log_attribute` — filters log-level attributes (e.g. "k8s.container.name", "http.method"). - `log_resource_attribute` — filters resource-level attributes (e.g. k8s labels, deployment info). - **Use `logs-list-attributes` to discover available attribute keys** before building filters. - **Use `logs-list-attribute-values` to discover valid values** for a specific attribute key. - **Find the suitable operator for the value type** (see supported operators below). Supported operators: - String: `exact`, `is_not`, `icontains`, `not_icontains`, `regex`, `not_regex` - Numeric: `exact`, `gt`, `lt` - Date: `is_date_exact`, `is_date_before`, `is_date_after` - Existence (no value needed): `is_set`, `is_not_set` The `value` field accepts a string, number, or array of strings depending on the operator. Omit `value` for `is_set`/`is_not_set`. ## Time period Use the `query.dateRange` field to control the time window. If the question doesn't mention time, the default is the last hour (`-1h`). Examples of relative dates: `-1h`, `-6h`, `-1d`, `-7d`, `-30d`. # Parameters All parameters go inside `query`. ## query.severityLevels Filter by log severity: `trace`, `debug`, `info`, `warn`, `error`, `fatal`. Omit to include all levels. ## query.serviceNames Filter by service names. Use `logs-list-attribute-values` with `key: "service.name"` to discover available services. ## query.searchTerm Full-text search across log bodies. Use this when the user is looking for specific text in log messages. ## query.orderBy Sort by timestamp: `latest` (default) or `earliest`. ## query.filterGroup A list of property filters to narrow results. Each filter specifies `key`, `operator`, `type` (log/log_attribute/log_resource_attribute), and optionally `value`. See the "Property filters" section above. ## query.dateRange Date range to filter results. Defaults to the last hour (`-1h`). - `date_from`: Start of the range. Accepts ISO 8601 timestamps or relative formats: `-1h`, `-6h`, `-1d`, `-7d`, `-30d`. - `date_to`: End of the range. Same format. Omit or null for "now". ## query.limit Maximum number of results (1-1000). Defaults to 100. ## query.after Cursor for pagination. Use the `nextCursor` value from the previous response. # Examples ## List recent error logs ```json { "query": { "severityLevels": ["error", "fatal"] } } ``` ## Search for a specific log message ```json { "query": { "searchTerm": "connection refused", "dateRange": { "date_from": "-6h" } } } ``` ## Filter logs from a specific service ```json { "query": { "serviceNames": ["api-gateway"], "dateRange": { "date_from": "-1d" } } } ``` ## Filter by a log attribute ```json { "query": { "filterGroup": [{ "key": "http.status_code", "operator": "exact", "type": "log_attribute", "value": "500" }], "dateRange": { "date_from": "-1d" } } } ``` ## Combine severity and attribute filters ```json { "query": { "severityLevels": ["error"], "filterGroup": [ { "key": "k8s.container.name", "operator": "exact", "type": "log_resource_attribute", "value": "web" } ], "dateRange": { "date_from": "-12h" } } } ``` ## Filter by log body content using property filter ```json { "query": { "filterGroup": [{ "key": "message", "operator": "icontains", "type": "log", "value": "timeout" }] } } ``` ## Check if an attribute exists ```json { "query": { "filterGroup": [{ "key": "trace_id", "operator": "is_set", "type": "log_attribute" }] } } ``` # Reminders - Ensure that any property filters are directly relevant to the user's question. Avoid unnecessary filtering. - Use `logs-list-attributes` and `logs-list-attribute-values` to discover attributes before guessing filter keys/values. - Prefer `searchTerm` for simple text matching; use `filterGroup` with type `log` and key `message` for regex or exact matching.
logs-attributes-list
List available log attribute names for filtering. Use attribute_type "log" for log-level attributes or "resource" for resource-level attributes (e.g. k8s labels).
logs-attribute-values-list
List values for a specific log attribute key. Use to discover what values exist for a given attribute before building filters.
notebooks-list
List all notebooks in the project. Supports filtering by search term, created_by, last_modified_by, date_from, date_to, and contains. Returns title, short_id, and creation/modification metadata.
notebooks-create
Create a new notebook. Provide a title and content. Content is a JSON object representing the notebook's rich text document structure (ProseMirror-based). Returns the created notebook with its short_id.
notebooks-retrieve
Get a specific notebook by its short_id. Returns the full notebook including title, content, version, and creation/modification metadata.
notebooks-partial-update
Update an existing notebook by short_id. Can update title, content, and deleted status. IMPORTANT: when updating the content field, you must provide the current version number for optimistic concurrency control. Retrieve the notebook first to get the latest version.
notebooks-destroy
Delete a notebook by short_id. The notebook will be soft-deleted and no longer appear in lists.
persons-list
List persons in the current project. Supports search by email (full text) or distinct ID (exact match), and filtering by email or distinct_id query parameters. Returns paginated results with person properties and distinct IDs.
persons-retrieve
Retrieve a single person by numeric ID or UUID. Returns the person's properties, distinct IDs, and metadata.
persons-property-delete
Remove a single property from a person by key. The property is deleted asynchronously via the event pipeline ($unset).
persons-property-set
Set a single property on a person. The property is updated asynchronously via the event pipeline ($set). Returns 202 Accepted.
persons-bulk-delete
Delete up to 1000 persons by PostHog person UUIDs or distinct IDs. Optionally delete associated events and recordings. Pass either `ids` (person UUIDs) or `distinct_ids`. Returns 202 Accepted. This operation is irreversible.
persons-cohorts-retrieve
Get all cohorts that a specific person belongs to. Requires the person_id query parameter.
persons-values-retrieve
Get distinct values for a person property key. Useful for discovering what values exist for properties like 'plan', 'role', or 'company'. Provide the property key and optionally a search value to filter results.
change-requests-list
List approval requests (change requests) for the current project. Returns pending, approved, rejected, and expired requests with vote status and staleness info. Useful for understanding what governance actions are waiting for review.
change-request-get
Get a specific change request by ID, including the full intent, policy snapshot, approval votes, and current state.
approval-policies-list
List all approval policies configured for this project. Shows which actions require approval, who can approve, and bypass rules.
approval-policy-get
Get details of an approval policy including conditions, approver configuration, quorum requirements, and bypass rules.
comments-list
List comments across the project. Filter by scope (Dashboard, FeatureFlag, Insight, etc.) and item_id to find discussions on specific resources. Returns comment content, author, and threading info.
comment-get
Get a specific comment by ID including its content, rich content with mentions, and metadata.
comment-thread
Get the full thread of replies for a parent comment. Useful for reading complete discussions on a resource.
comment-count
Get the count of comments, optionally filtered by scope and item_id.
activity-log-list
List recent activity log entries for the project. Shows who did what and when — feature flag changes, dashboard edits, experiment launches, etc. Supports filtering by scope, user, and date range.
advanced-activity-logs-list
List activity log entries with advanced filtering, sorting, and field-level diffs. Supports filtering by scope, activity type, user, date range, and search text.
advanced-activity-logs-filters
Get the available filter options for activity logs — scopes, activity types, and users that have logged activity. Useful for building filter UIs or understanding what kinds of activity are tracked.
org-members-list
List all members of the current organization with their names, emails, membership levels (member, admin, owner), and last login times.
roles-list
List all roles defined in the organization. Roles group members and can be used in approval policies and access control rules.
role-get
Get details of a specific role including its name, creation date, and creator.
role-members-list
List all members assigned to a specific role. Shows who has which role in the organization.
prompt-list
List all LLM prompts stored for the current team. Optionally filter by name. Returns paginated prompt summaries. By default, only prompt metadata is returned, not full prompt content.
prompt-get
Get a specific LLM prompt by name, including its full content. Uses the cached endpoint for fast retrieval.
prompt-create
Create a new LLM prompt for the current team. Requires a unique name and prompt content (string or JSON object).
prompt-update
Publish a new version of an existing LLM prompt by name. Name is immutable after creation. You can either provide the full prompt content via 'prompt', or use 'edits' for incremental find/replace updates. Each edit must have 'old' (text to find, must match exactly once) and 'new' (replacement text). Edits are applied sequentially. Only one of 'prompt' or 'edits' may be provided.
prompt-duplicate
Duplicate an existing LLM prompt under a new name. Copies the latest version's content to create a new prompt at version 1. Useful for forking a prompt or as a way to rename since names are immutable after creation.
proxy-list
List all managed reverse proxies configured for the current organization. Returns each proxy's domain, CNAME target, provisioning status, and the maximum number of proxies allowed by the current plan. Use this to check whether a reverse proxy is set up before recommending one.
proxy-get
Get full details of a specific reverse proxy by ID. Returns the domain, CNAME target (the DNS record value the user needs to configure), current provisioning status, and any error or warning messages. Use this to debug why a proxy isn't working or to check DNS verification status.
proxy-create
Create a new managed reverse proxy for a custom domain. Provide the domain (e.g. 'e.example.com') that will proxy requests to PostHog. The response includes the CNAME target — the user must add a CNAME DNS record pointing their domain to this target. Once DNS propagates, the proxy is automatically verified and an SSL certificate is issued. The proxy starts in 'waiting' status until DNS is verified.
proxy-retry
Retry provisioning a reverse proxy that has failed. Only works for proxies in 'erroring' or 'timed_out' status. Resets the proxy to 'waiting' and restarts the DNS verification and certificate provisioning workflow.
proxy-delete
Delete a managed reverse proxy. For proxies still being set up (waiting, erroring, timed_out), the record is removed immediately. For active proxies, a cleanup workflow is started to remove the provisioned infrastructure.
workflows-list
List all workflows in the project. Returns workflows with their name, description, status (draft/active/archived), version, trigger configuration, and timestamps.
workflows-get
Get a specific workflow by ID. Returns the full workflow definition including trigger, edges, actions, exit condition, and variables.