Documentation

Analytics

Promptmark can send the AI events it generates – conversations, tests, playbook executions, Compose drafts, Conduct runs, Orchestrate proposals – to a PostHog project you own. Your keys, your project, your data.

This is a bring-your-own-keys (BYOK) integration. Promptmark never owns or shares your analytics data; it just emits events to the PostHog instance you point it at.

What You’ll See

Once configured, every AI generation Promptmark runs on your behalf shows up in your PostHog project as a $ai_generation event with full lifecycle properties:

  • Model and provider (e.g. anthropic/claude-sonnet-4.6, routed via OpenAI direct, Anthropic direct, or OpenRouter)
  • Token counts – prompt tokens, completion tokens, total
  • Cost estimate in USD
  • Latency – time to first token (TTFT) and total wall-clock duration
  • Outcome – success, error, or finish reason (stop, length, etc.)
  • Source surface – which Promptmark feature generated it (Conversation, Test, Playbook, Compose, Conduct, Guide, Orchestrate)

You also get product events: prompt_shared, prompt_published, collection_created, prompt_remixed, playbook_completed, playbook_failed, and a one-shot first_value_reached milestone.

PostHog handles the rest – dashboards, funnels, retention, alerts. Promptmark just feeds the events.

What You Need from PostHog

You need a PostHog account and a project. Two keys come from there:

Key Format Required Purpose
Project API key phc_... Yes Write-only ingest token. Promptmark uses this to send events to your project.
Personal API key phx_... No Read access. Unlocks the in-app Analytics page so Promptmark can show you your own event stream.

The project key alone is enough for Promptmark to send events. Add the personal key if you want Promptmark’s Analytics page to display extended (7-day) stats pulled from your PostHog project directly.

Both keys are encrypted at rest using AES-256 (AES-GCM) and never displayed after saving.

Configuring Analytics

  1. Navigate to Connections
  2. Find the PostHog section
  3. Paste your Project API key (phc_...)
  4. Optionally paste your Personal API key (phx_...)
  5. Choose your PostHog host:
    • https://us.i.posthog.com (PostHog Cloud US, default)
    • https://eu.i.posthog.com (PostHog Cloud EU)
    • Your own self-hosted PostHog URL (must be HTTPS)
  6. Toggle Enabled on
  7. Click Save

After saving, click Test to confirm Promptmark can reach your PostHog project and that the keys are valid.

Warning
PostHog hosts must be HTTPS and must not point to internal or private network addresses (localhost, private IPs, link-local, cloud metadata endpoints). This is an SSRF protection measure and cannot be bypassed.

The Analytics Page

Navigate to Analytics in the sidebar to see your event stream inside Promptmark. The page has three progressive states:

State When You See It What’s Shown
Disconnected No PostHog configured An empty state with a CTA pointing to Connections
Project key only Project key set + enabled Recent events log + today’s stats (events, tokens, cost, errors)
Personal key set Both keys configured Extended 7-day stats pulled from PostHog directly

The recent events log is stored locally in your Promptmark database and shows the last 10 events with model, source, tokens, cost, and latency. Today’s and 7-day rollups aggregate the same events into top-level metrics.

Disabling

Toggle Enabled off in Connections to pause event delivery without removing your keys. New events stop being sent immediately. Re-enable any time and event delivery resumes.

To remove your keys entirely, click Delete configuration in Connections. This wipes the encrypted keys from your account.

MCP Tools

Analytics configuration is available via MCP tools:

Tool Description
configure_posthog Save or update your PostHog project key, personal key, host, and enabled state. Validates key prefixes and host scheme; encrypts keys at rest.
get_posthog_status Get the current configuration status – whether keys are set, the host, and whether the integration is enabled. Never returns decrypted keys.

For full schemas, see the MCP Reference.

Tips

  • Set up a PostHog dashboard first. Promptmark sends events with consistent property names; pin the ones you care about (cost, latency, error rate, model split) into a dashboard before traffic builds up.
  • Use the surface super-property to slice. Every event tags the surface that generated it (Conversation, Test, Playbook, Compose, etc.) – group by it to see which features drive the most usage and cost.
  • Personal key is optional but worth it. Without it, you can still see events in PostHog directly; the Promptmark Analytics page just won’t pull extended stats.
  • EU host for EU residents. PostHog Cloud EU keeps event storage inside the EU. Self-hosted PostHog keeps it inside your infrastructure entirely.

What’s Next