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_logtable 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 case | Recommendation |
|---|---|
| Ad-hoc and explorative queries | Query API |
| Scheduled or recurring queries (cron jobs, weekly reports, pipelines) | Endpoints |
| Production application | Endpoints |
| Customer-facing analytics | Endpoints |
| High traffic | Endpoints |
| Data exports to a third-party (i.e. S3 or Snowflake) | Batch exports |





