Endpoints vs Query API

Contents

PostHog offers two ways to run queries programmatically: the Query API and Endpoints. Here's how they differ and when to use each.

Query API

The Query API is a free-form API that lets you run any query. While flexible, it has some drawbacks:

  • Impossible to optimize - Not knowing the query ahead of time makes it hard for us to help you get better performance.
  • Harder to monitor - Tracking query performance over time requires querying the system.query_log table manually.
  • Future pricing - We strongly discourage Query API usage and will eventually charge for it.

Endpoints

Endpoints provide a more stable, purpose-built solution for production use cases:

  • Isolated compute - Materialized endpoints run on separate compute, avoiding the noisy neighbor problem and enabling better rate/concurrency limits.
  • Easy monitoring - The Usage tab shows performance metrics out of the box.
  • Developer experience - First-class features like versioning, OpenAPI specs, and easy configuration.
  • Cost and speed controls - Materialization and caching let you trade data freshness for performance.
  • Abuse prevention - Individual endpoints can be disabled if needed.

When to use each

If a query runs on a schedule or repeatedly from your own servers, use an endpoint, even when you're only querying your own data and it isn't customer-facing. Scheduled Query API calls are the most common source of timeouts and capacity or concurrency errors, because they run on shared compute. Endpoints can run on isolated compute and cache or materialize results.

Use caseRecommendation
Ad-hoc and explorative queriesQuery API
Scheduled or recurring queries (cron jobs, weekly reports, pipelines)Endpoints
Production applicationEndpoints
Customer-facing analyticsEndpoints
High trafficEndpoints
Data exports to a third-party (i.e. S3 or Snowflake)Batch exports

Still have questions?

Was this page useful?