: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 endpoints
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product endpoints
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
category: Endpoints
feature: endpoints
url_prefix: /endpoints
ui_apps: {}
tools:
endpoint-create:
operation: endpoints_create
enabled: true
scopes:
- endpoint:write
annotations:
readOnly: false
destructive: false
idempotent: false
enrich_url: '{name}'
title: Create endpoint
description: >
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). Set is_materialized to true to materialize an
eligible query.
include_params:
- name
- query
- description
- is_materialized
- data_freshness_seconds
- tags
endpoint-delete:
operation: endpoints_destroy
enabled: true
scopes:
- endpoint:write
annotations:
readOnly: false
destructive: true
idempotent: true
title: Delete endpoint
description: |
Delete an endpoint by name. The endpoint is soft-deleted and its materialized views are cleaned up.
soft_delete: true
endpoint-get:
operation: endpoints_retrieve
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{name}'
title: Get endpoint
description: >
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-logs:
operation: endpoints_logs_retrieve
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: Get endpoint logs
description: >
Retrieve execution logs for an endpoint by name. Each run emits one entry with a timestamp, level (INFO or
ERROR), and a message whose extra data is in key=value tokens (path=materialized|inline|ducklake,
cache=hit|miss, duration_ms=, rows=, version=, error=). Filter by level (e.g. "ERROR"), text search (e.g.
"cache=miss"), time range (after/before), a specific execution (instance_id), and limit (max 500). Use to
debug why an endpoint failed, timed out, missed cache, or returned unexpected row counts.
endpoint-materialization-status:
operation: endpoints_materialization_status_retrieve
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{name}'
title: Get materialization status
description: >
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:
operation: endpoints_openapi_spec_retrieve
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get endpoint OpenAPI spec
description: >
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.
endpoint-run:
operation: endpoints_run_create
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{name}'
title: Run endpoint
description: >
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.
include_params:
- variables
- limit
- offset
- refresh
param_overrides:
variables:
description: >
Key-value pairs to parameterize the query. For HogQL endpoints, keys match variable code_name (e.g.
{"event_name": "$pageview"}). For insight endpoints with breakdowns, use the breakdown property name
as key.
endpoint-update:
operation: endpoints_partial_update
enabled: true
scopes:
- endpoint:write
annotations:
readOnly: false
destructive: false
idempotent: true
enrich_url: '{name}'
title: Update endpoint
description: >
Update an existing endpoint by name. Can update the query (auto-creates a new version), description, data
freshness, active status, and materialization. Pass version in body to target a specific version for
non-query updates.
include_params:
- query
- description
- is_active
- is_materialized
- data_freshness_seconds
- version
- tags
endpoint-versions:
operation: endpoints_versions_list
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{name}'
list: true
title: Get endpoint versions
description: >
List all versions for an endpoint, in descending order (latest first). Each version contains the query
snapshot, description, data freshness, last execution time, and materialization status at that point in
time.
endpoints-get-all:
operation: endpoints_list
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{name}'
list: true
title: Get all endpoints
description: >
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.
endpoints-last-execution-times:
operation: endpoints_last_execution_times_create
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get endpoints last execution times
description: >
Get the most recent execution time per endpoint (endpoint-level, personal API key calls only). Pass an array
of endpoint names; returns rows shaped [name, last_executed_at]. Endpoints never called are omitted from the
response. Use this for a quick endpoint-level recency check during an audit; for per-version usage or
history, query the query_log table with execute-sql.
include_params:
- names
endpoints-materialization-preview:
operation: endpoints_materialization_preview_create
enabled: true
scopes:
- endpoint:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{params.name}'
title: Preview endpoint materialization
description: >
Preview the materialization transform for an endpoint before enabling it. Returns the transformed HogQL,
detected range pairs, and aggregate re-aggregation info, plus a rejection reason if the query is not
eligible. Supports an optional version body param. Read-only — does not enable materialization.
include_params:
- version
- bucket_overrides