← All runbooks
jetty-corp / posthog-usage-summary

PostHog Usage Summary

Pull product analytics from PostHog for the Jetty project and produce a concise usage summary covering two time windows: the last 24 hours and the last 7 days. The report quantifies overall activity (events, sessions, active users), highlights the most-used…

agent claude-codemodel claude-sonnet-4-6snapshot python312-uveval programmatic7 stepsv1.0.0

Deploy PostHog Usage Summary to your jetty.io

One-click installs this runbook into a collection on your Jetty account. You can run it from the Spot dashboard, schedule it, or pipe inputs in via the API.

Deploy on jetty.io →View source
The shape of the run

7 steps · start to finish.

  1. 1
    Step 1

    Environment Setup

    ▶
    # Install dependencies
pip install httpx python-dateutil

# Create output directory
mkdir -p {{results_dir}}

# Verify required secrets are available
for var in POSTHOG_PERSONAL_API_KEY POSTHOG_PROJECT_ID; do
  if [ -z "${!var}" ]; then
    echo "ERROR: $var is not set. Add it to the jetty-corp collection env on Jetty (or export locally)."
    exit 1
  fi
done

echo "Environment ready. Project: $POSTHOG_PROJECT_ID  Host: {{posthog_host}}"

    Verify credentials and the host URL respond before running real queries:

    curl -sS -o /dev/null -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  "{{posthog_host}}/api/projects/$POSTHOG_PROJECT_ID/"
# Expect: HTTP 200

    If you get 401, the key is missing or lacks scopes. If 404, the project ID is wrong or the host is wrong (US vs EU cloud).

  2. 2
    Step 2

    Collect Metrics from PostHog

    ▶

    Use the PostHog Query API with HogQL to compute metrics for both windows in one pass per metric. Run all queries against the project endpoint:

  3. 3
    Step 3

    Build the Report

    ▶

    Compose {{results_dir}}/usage_summary.md using this structure:

  4. 4
    Step 4

    Evaluate Outputs

    ▶

    Score each window's data and the report against these criteria:

  5. 5
    Step 5

    Iterate on Errors (max 3 rounds)

    ▶

    If evaluation returns FAIL or PARTIAL:

  6. 6
    Step 6

    Write Executive Summary

    ▶

    Write {{results_dir}}/summary.md:

  7. 7
    Step 7

    Write Validation Report

    ▶

    Write {{results_dir}}/validation_report.json: