posthog-analytics

name	posthog-analytics
description	PostHog API expertise for GTM dashboards — REST API, HogQL, funnels, cohorts, UTM attribution

PostHog Analytics for GTM

Build and manage analytics dashboards, funnels, and cohort analyses programmatically via the PostHog API. This skill covers the REST API, HogQL query patterns, and GTM-specific dashboard construction.

Authentication

All API requests require a personal API key or project API key:

# Headers for all requests
Authorization: Bearer phx_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Base URL format: https://us.posthog.com (US) or https://eu.posthog.com (EU)

Project ID: Required for most endpoints. Found in PostHog > Project Settings.

Key API Endpoints

Endpoint	Method	Purpose
/api/projects/:id/dashboards/	GET/POST	List or create dashboards
/api/projects/:id/insights/	GET/POST	List or create insights (charts)
/api/projects/:id/insights/trend/	POST	Run trend query
/api/projects/:id/insights/funnel/	POST	Run funnel query
/api/projects/:id/cohorts/	GET/POST	List or create cohorts
/api/projects/:id/events/	GET	List captured events
/api/projects/:id/persons/	GET	List persons with properties
/api/projects/:id/query/	POST	Run HogQL queries
/api/projects/:id/feature_flags/	GET/POST	Manage feature flags

Dashboard Creation

Create a Dashboard

POST /api/projects/:project_id/dashboards/
{
  "name": "GTM Campaign Performance",
  "description": "Tracks paid acquisition funnel and campaign ROI",
  "filters": {},
  "restriction_level": 21,
  "tags": ["gtm", "paid-acquisition"]
}

Add Insight Tiles to a Dashboard

After creating insights, link them to a dashboard:

PATCH /api/projects/:project_id/dashboards/:dashboard_id/
{
  "tiles": [
    {
      "insight": INSIGHT_ID,
      "layouts": {
        "sm": {"x": 0, "y": 0, "w": 6, "h": 5},
        "xs": {"x": 0, "y": 0, "w": 1, "h": 5}
      }
    }
  ]
}

Layout Grid

• Dashboard uses a 12-column grid (sm breakpoint)
• w: width in columns (1-12), h: height in rows, x/y: position
• Standard sizes: full-width = w:12, h:8, half = w:6, h:5, quarter = w:3, h:5

Insight Types

Trend Insight (Time Series)

POST /api/projects/:project_id/insights/
{
  "name": "Daily Signups by UTM Source",
  "filters": {
    "insight": "TRENDS",
    "events": [
      {
        "id": "user_signed_up",
        "type": "events",
        "math": "total",
        "properties": []
      }
    ],
    "breakdown": "$utm_source",
    "breakdown_type": "event",
    "date_from": "-30d",
    "interval": "day"
  }
}

Funnel Insight

POST /api/projects/:project_id/insights/
{
  "name": "Signup to Payment Funnel",
  "filters": {
    "insight": "FUNNELS",
    "events": [
      {"id": "$pageview", "order": 0, "properties": [{"key": "$current_url", "value": "/landing", "operator": "icontains"}]},
      {"id": "user_signed_up", "order": 1},
      {"id": "onboarding_completed", "order": 2},
      {"id": "plan_selected", "order": 3},
      {"id": "payment_completed", "order": 4}
    ],
    "funnel_window_days": 14,
    "funnel_viz_type": "steps",
    "date_from": "-30d",
    "breakdown": "$utm_source",
    "breakdown_type": "event"
  }
}

Retention Insight

POST /api/projects/:project_id/insights/
{
  "name": "Weekly Retention by Cohort",
  "filters": {
    "insight": "RETENTION",
    "target_entity": {"id": "$pageview", "type": "events"},
    "returning_entity": {"id": "$pageview", "type": "events"},
    "retention_type": "retention_first_time",
    "period": "Week",
    "total_intervals": 8,
    "date_from": "-60d"
  }
}

HogQL Queries

HogQL is PostHog's SQL dialect built on ClickHouse. Use it for custom analyses that go beyond built-in insights.

Running a HogQL Query

POST /api/projects/:project_id/query/
{
  "query": {
    "kind": "HogQLQuery",
    "query": "SELECT properties.$utm_source AS source, count() AS signups FROM events WHERE event = 'user_signed_up' AND timestamp > now() - interval 30 day GROUP BY source ORDER BY signups DESC LIMIT 20"
  }
}

Key HogQL Tables

Table	Contains
events	All tracked events with properties
persons	User profiles with properties
sessions	Session-level data with duration, pages, etc.
groups	Group analytics (companies, organizations)
cohort_people	Which persons belong to which cohorts
session_replay_events	Session replay metadata

Key Event Properties

Property	Description
$current_url	Page URL where event fired
$referrer	Referrer URL
$utm_source	UTM source parameter
$utm_medium	UTM medium parameter
$utm_campaign	UTM campaign parameter
$utm_content	UTM content parameter
$utm_term	UTM term parameter
$browser	Browser name
$device_type	Desktop, Mobile, Tablet
$os	Operating system
$geoip_country_code	Country code (ISO)
$geoip_city_name	City name

Cohort Creation

Property-Based Cohort

POST /api/projects/:project_id/cohorts/
{
  "name": "Paid Acquisition Users (Last 30d)",
  "is_static": false,
  "groups": [
    {
      "properties": [
        {
          "key": "$utm_medium",
          "value": ["paid", "cpc", "cpm"],
          "operator": "exact",
          "type": "person"
        },
        {
          "key": "$initial_utm_source",
          "value": "meta",
          "operator": "exact",
          "type": "person"
        }
      ],
      "days": 30
    }
  ]
}

Behavioral Cohort

POST /api/projects/:project_id/cohorts/
{
  "name": "Activated Users (completed onboarding)",
  "is_static": false,
  "groups": [
    {
      "action_id": null,
      "event_id": "onboarding_completed",
      "days": 90,
      "count": 1,
      "count_operator": "gte"
    }
  ]
}

GTM Dashboard Recipes

Standard GTM Dashboard Tiles

1. Signup Volume by Source -- Trend, daily, breakdown by $utm_source
2. Acquisition Funnel -- Funnel: visit > signup > onboarding > activation > payment
3. CAC by Campaign -- HogQL joining event data with spend data
4. Geo Distribution -- Trend, breakdown by $geoip_country_code
5. Device Split -- Trend, breakdown by $device_type
6. Landing Page Performance -- Trend, breakdown by $current_url filtered to /landing*
7. Weekly Retention -- Retention chart, first-time retention, 8-week window
8. Conversion Rate Over Time -- HogQL: signups / unique visitors per day