Endpoints
Contents
Endpoints turn a saved insight or SQL query into a named, callable API route. You write the query once in PostHog, give it a name, and your app fetches the results over HTTP – no query strings to assemble in client code, and no query logic scattered across your services.
Because the query lives in PostHog, you get versioning, execution logs, and optional materialization for free. That makes endpoints a good fit for customer-facing analytics and internal tools, where the same query runs constantly and needs to stay fast and predictable.
Want to see one in production? Our MCP leaderboard is powered by two endpoints. See public stats pages for how it works.
When to use Endpoints
Use an endpoint whenever code, not a person, runs a PostHog query:
- Backend services and scheduled jobs that pull counts, sums, or breakdowns on a schedule or per request.
- Customer-facing analytics, where each of your users sees their own stats. Pass each user's or customer's ID as a variable instead of building SQL strings.
- Internal tools and scripts that run the same query more than once.
For heavy aggregates that run often, turn on materialization so requests read a precomputed table instead of scanning events. Not every query can be materialized. The materialization page lists the rules.
Use something else when:
- You're exploring data or asking one-off questions. Use the SQL editor, the query API, or the PostHog MCP from an AI agent.
- You're exporting raw events or persons to a warehouse. Use batch exports.
Move a /query call to an endpoint
If your code calls /api/projects/:project_id/query/:
Paste the SQL from your code into the SQL editor and run it.
Replace values your code changes on each call, like a user ID or a date, with variables:
WHERE properties.user_id = {variables.user_id}. Then add each variable in the Variables tab with its type, for exampleuser_idas aString. You can't create the endpoint while the query uses a variable that isn't defined.Create an endpoint from the query. If it aggregates over a lot of events, turn on materialization.
Get an API key with the
endpoint:readscope. A key that only has the Query Read permission can't run endpoints. See authentication for which key type to use.In your code, replace the
/queryrequest with a request to the endpoint:TerminalTo page through results from a SQL endpoint, pass
limitandoffsetin the request body. Endpoints built from insights don't support pagination.
If your code pages through raw rows to copy them somewhere else, move it to batch exports instead.
Where you can use it
You build and monitor endpoints in the PostHog web app, then call them from your own code. MCP and PostHog Desktop are for creating and debugging endpoints from an AI tool.
PostHog Web
Create endpoints, test them in the playground, and watch usage and execution logs.
Build an endpoint →API
Call your endpoint over HTTP from any language, or generate a typed client from its OpenAPI spec.
Call an endpoint →PostHog MCP
Create, run, version, and debug endpoints from Claude Code, Cursor, or any MCP client.
Manage endpoints →Where its data comes from
An endpoint doesn't store data of its own. It serves whatever its query returns, shaped by the variables you pass and the way it's executed.
Insights
Publish a saved insight as an endpoint and serve the same numbers your dashboards show.
Endpoint types →SQL queries
Write SQL against your events, persons, and data warehouse tables, then expose the result.
Variables →Materialized tables
Eligible queries are precomputed on a schedule so requests read a table instead of scanning events.
How materialization works →Execution logs
Every run records its duration, row count, cache path, and error, across all versions.
Usage and logs →




