What It Does

Patterns for programmatic analytics using the PostHog API. Creating insights, building funnels, querying with HogQL, managing dashboards, and avoiding the common pitfalls that waste hours.

The Pattern

Analytics APIs let agents create dashboards, query data, and surface insights without touching a browser. The core patterns are universal across analytics platforms, though the specifics here use PostHog.

The InsightVizNode wrapper is the single most important pattern. When creating dashboard visualizations via API, the query must be wrapped in a visualization node. Without it, the dashboard shows raw JSON instead of a chart. This is PostHog-specific but illustrates a general API principle: rendering and querying are separate concerns.

{
  "query": {
    "kind": "InsightVizNode",
    "source": {
      "kind": "FunnelsQuery",
      "series": [
        {"kind": "EventsNode", "event": "signup"},
        {"kind": "EventsNode", "event": "purchase"}
      ],
      "dateRange": {"date_from": "-7d"}
    }
  }
}

HogQL (SQL-like querying) enables complex analysis that pre-built insight types can't handle. Key patterns:

• Set intersection for cohort analysis: use groupArray + HAVING to find users who did both event A and event B, in a single query
• Platform attribution: combine client-side library identifiers with server-side event properties for accurate platform breakdowns
• Always include LIMIT: large queries can timeout or truncate silently

Survey response querying has a critical gotcha: responses use UUID-based property names in a JSON array, not simple indexed fields. The field is $survey_questions, not $survey_response_1. Getting this wrong returns null for every response.

Dashboard management via API:

• Create insights with saved: true to persist them
• Delete tiles using PATCH with deleted: true (there's no DELETE endpoint)
• API responses return 201 success even for malformed visualizations. PostHog doesn't validate rendering compatibility on creation.

Dev environment isolation: prevent local development from polluting production analytics by checking the environment before initializing the SDK. One line of defense that prevents hours of confusion from mixed data.

Key Decisions

HogQL over complex insight chains. For anything beyond simple trends and funnels, writing SQL is faster and more debuggable than chaining multiple insight types together. It also composes better when you need to compute across events.

Inline credential loading. For agent-driven analytics, load API keys from environment files within the query command itself. This avoids exported environment variables leaking across processes.

Freshness buffers for monitoring. When building automated volume monitors, include a 15-minute buffer (e.g., check now - 75 minutes to now - 15 minutes). Analytics ingestion has latency. Without a buffer, you get false alarms from events that haven't been processed yet.

Transformation filters can silently drop everything. A misconfigured event filter in the data pipeline can cause all events except exceptions to disappear. If you see only $exception events surviving, check transformation filters immediately.

When to Use It

• Building automated analytics dashboards via API
• Creating agent-driven reporting workflows (daily metrics, weekly summaries)
• Querying analytics data programmatically for decision support
• Debugging analytics pipelines (missing events, stale data, conflicting numbers)