Use cases and tips

Common use cases

Customer-facing dashboards

If you need to show a subset of your analytics to your own customers, endpoints provide a secure, performant way to do this.

Example: Create an endpoint from a "Daily Active Users" insight and display it in your customer dashboard.

Predefined queries

For queries you run frequently, endpoints provide a stable, optimized way to programmatically access the data without reconstructing the query each time.

Example: Create an endpoint for "Top 10 events this week" that your team or AI agent can call regularly.

Public stats pages

Endpoints work well for public pages built from your own product data, like leaderboards, usage reports, or "state of" pages. The query and its aggregation rules live in PostHog, and your site only fetches the results.

Example: The MCP leaderboard on posthog.com runs on two SQL endpoints over $mcp_tool_call events: one groups by week and one by day. Each refreshes daily. When the site builds, it calls both endpoints once and bakes the results into the page, so visitors never wait on a query.

Treat the endpoint output as public

Anything the endpoint returns ends up in your page data, even columns you don't render. Aggregate in the query itself: return shares and rates instead of raw counts, and fold small groups into an "Other" bucket.

Performance tips

Use materialization

For better performance, consider materializing your endpoint. Materialized queries are precomputed, which can significantly improve endpoint response times.

Cache responses

Endpoints return cached data when available. You can configure the TTL of cached results based on your requirements. If the cache is older than your desired freshness, the endpoint will execute the query again (and cache those results). Endpoints should eliminate the need for you to implement your own caching layer.

Optimize your queries

The performance of your endpoints depends on the underlying queries. Follow best practices for writing performant queries:

Use shorter time ranges.
Avoid scanning the same table multiple times.
Use materialized views for frequently accessed data. Your endpoint can depend on another materialized view.
Include appropriate filters to limit data scanned.