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.

Get started

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/:

  1. Paste the SQL from your code into the SQL editor and run it.

  2. 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 example user_id as a String. You can't create the endpoint while the query uses a variable that isn't defined.

  3. Create an endpoint from the query. If it aggregates over a lot of events, turn on materialization.

  4. Get an API key with the endpoint:read scope. A key that only has the Query Read permission can't run endpoints. See authentication for which key type to use.

  5. In your code, replace the /query request with a request to the endpoint:

    Terminal
    curl -X POST \
    -H "Authorization: Bearer $POSTHOG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"variables": {"user_id": "user_123"}}' \
    "<ph_app_host>/api/environments/{project_id}/endpoints/{endpoint_name}/run"

    To page through results from a SQL endpoint, pass limit and offset in 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 →

Still have questions?

Was this page useful?