skills.rest
PostHog
PostHogOFFICIAL
Explore all skills by this author →
Website𝕏@PostHogGitHub

creating-an-endpoint

Creates PostHog endpoints exposing HogQL or insight queries as callable HTTP API routes.

713|118|Updated Aug 11, 2020
Search Tags:#api#cache#endpoint#materialization#PostHog#Query#HogQL
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill creating-an-endpoint
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: creating-an-endpoint
Source: https://github.com/PostHog/posthog-foss/tree/main/products/endpoints/skills/creating-an-endpoint
Command: npx skills add https://github.com/PostHog/posthog-foss --skill creating-an-endpoint

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Configuring a new PostHog endpoint involves several consequential decisions — query kind, variable design, cache TTL, and materialisation — that are hard to change later because the endpoint name lives in the URL callers depend on. This Skill walks through each decision in order so the endpoint is created with the right shape on the first try, avoiding common mistakes like materialising ineligible queries or leaving variables without defaults.

Core Features & Use Cases

  • Guided decision workflow: Covers whether an endpoint is the right tool, naming conventions, HogQL vs insight query kinds, variable design, data_freshness_seconds selection, and day-one materialisation.
  • Materialisation deep-dive: A bundled reference explains eligibility rules, bucket overrides for range variables, refresh schedules, and per-version materialisation behavior.
  • Use Case: A user wants to expose a monthly active users query as an API for an external analytics partner. The Skill helps pick the name, declare lookback_days and org_id variables, set a 3600-second cache TTL, skip materialisation initially, then create and test the endpoint with a sample payload.

Quick Start

Ask the assistant to create a PostHog endpoint that exposes your saved HogQL query as a callable API with the variables and freshness interval you need.

Frequently Asked Questions about creating-an-endpoint

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a PostHog endpoint from a HogQL query?▼

Define your HogQL query with variables using {variables.x} syntax, declare each variable with code_name, type, and a default, then call endpoint-create with the query and configuration. Verify the result by calling endpoint-run with a sample payload.

Should I use a HogQL query or an insight for my PostHog endpoint?▼

HogQL is the more flexible default and gives exact control over response columns. Choose insight only when re-publishing an existing Trends, Lifecycle, or Retention insight; other kinds like FunnelsQuery cannot be materialised or expose breakdown variables.

When should I enable materialisation on a PostHog endpoint?▼

Materialise when the endpoint is called frequently, the query takes over a second inline, and callers tolerate staleness equal to the refresh interval. Skip it for low-traffic or exploratory endpoints, and always run endpoints-materialization-preview first to confirm eligibility.

Why was my PostHog endpoint materialisation rejected?▼

Common rejection reasons include cohort breakdowns, compare mode, unresolved variables without defaults, non-deterministic functions like now(), and variable filters applied across JOINs. The endpoints-materialization-preview tool returns the exact rejection reason and the transformed query.

What values can data_freshness_seconds have on a PostHog endpoint?▼

The value must be one of a fixed set: 900, 1800, 3600, 21600, 43200, 86400 (default), or 604800 seconds. It controls both the cache TTL and, on materialised endpoints, how often the materialised view is refreshed.

Can I rename a PostHog endpoint after creating it?▼

Renaming is not trivially supported because the name appears in the URL path /api/projects/{team_id}/endpoints/{name}/run that callers depend on. Pick a descriptive snake_case name without versions at creation time.

Related Skills

Explore More Software Engineering Skills→
PostHogPostHog
75

querying-posthog-data

Query PostHog analytics data using HogQL and SQL foundations.

Official
Intermediate
HabibTorjmenHabibTorjmen

benchmark-chonk

Benchmark Chonk client-IOV proving with pinned IVC inputs for native and WASM runs.

Community
Advanced
buvisbuvis
2

audit-plugins

Audit installed plugins and caches to identify stale versions and reclaimable disk space.

Official
Intermediate
clawdataclawdata
24

data-analysis

Run SQL queries to explore datasets and generate inline chart blocks.

Official
Advanced