Product analytics API

Use the API to run analytics queries and manage saved insights from your own systems – a nightly report, an internal admin tool, or a customer-facing dashboard you build yourself.

There are two things worth knowing about. The query endpoint runs any analytics query and hands back results, and the insights endpoints create, read, update, and delete the insights people see in the web app.

Run a query

POST /api/projects/:project_id/query/ takes a query node – trends, funnels, retention, paths, stickiness, lifecycle, or raw SQL – and returns the results. This is the same endpoint the web app uses, so anything you can build as an insight you can run over the API.

curl -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": {"kind": "HogQLQuery", "query": "select event, count() from events group by event order by count() desc limit 10"}}' \
  https://us.posthog.com/api/projects/:project_id/query/

See the query API reference for the full request and response shape.

Manage insights

/api/projects/:project_id/insights/ lists, creates, updates, and deletes saved insights, and can run the query behind one to get fresh results. Use it to keep insights in sync with something else you own, or to create insights programmatically as part of onboarding a new customer or team.

Authentication

Use a personal API key passed as a bearer token, scoped to the smallest set of permissions the job needs. Reading insights needs insight:read; creating or updating them needs insight:write.

Related

• Build the same insights by hand in the web app.
• Ask for them conversationally over MCP.
• See the full PostHog API reference.