Call endpoints from your app

The API is where endpoints earn their keep. Your app makes one authenticated request to a named route, and PostHog runs the saved query and returns the rows – no query construction in client code, and no analytics logic spread across your services.

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

Before you start

1. Create an endpoint – define your data and publish it so there's an endpoint to call.
2. Get API access – create a personal API key with the scopes you need. See authentication below.

What you can do here

• Parameterize the query – pass variables so one endpoint serves many customers, date ranges, or breakdowns.
• Page through results – use limit and offset for large result sets.
• Pin to a version – target a specific version so a query change doesn't break a deployed client.
• Generate a typed client – each endpoint publishes an OpenAPI 3.0 spec you can feed to openapi-generator or @hey-api/openapi-ts. See OpenAPI SDK generation.

Authentication

Requests use either a project secret API key or a personal API key, both scoped to endpoint:read. Project secret keys are the right choice for backend services since they aren't tied to a user account, but they're in beta and rolling out gradually – if they aren't available in your organization yet, use a personal API key.

Never ship either key in client-side code. For customer-facing analytics, proxy the request through your own backend and pass the customer identifier as a variable.

Related

• Worked examples in cURL, Python, Node.js, TypeScript, and Go: retrieve your data.
• What happens between your request and the response: how execution works.
• How many requests you can make: rate limits.
• When to use an endpoint instead of a raw query: endpoints vs the query API.