API

PostHog has a powerful API that enables you to capture, evaluate, create, update, and delete nearly all of your information in PostHog. You can use it to pull information into your app, update metadata programmatically, capture events from any language that can send HTTP requests, and more.

The API is available for all users and instances. It contains two types of endpoints:

1. Public POST-only endpoints used for capturing events, batching events, updating person or group information, and evaluating feature flags. These don't require authentication, but use your project API key to handle the request.

2. Private GET, POST, PATCH, DELETE endpoints used for creating, updating, or deleting nearly all other non-event data in PostHog. They give the same access as if you were logged into your PostHog instance, but require authentication with your personal API key.

You must make API requests to the correct domain. These are https://us.posthog.com for US Cloud, https://eu.posthog.com for EU Cloud, and your self-hosted domain for self-hosted instances. Confirm yours by checking your URL from your PostHog instance.

Private endpoint authentication

Personal API keys enable full access to your account, like an email address and password. You can create multiple and each can be invalidated individually. This improves the security of your PostHog account.

How to obtain a personal API key

1. Go to Account settings
2. In the 'Personal API Keys' section, click "+ Create a Personal API Key".
3. Give your key a label – this is just for you, usually to describe the key's purpose.
4. Choose the scopes for your key. We recommended selecting only the scopes required for the API endpoints you really need. This is a security best practice. You can always modify the scopes later if you need to.
5. At the top of the list, you should see your brand new key. Immediately copy its value, as you'll never see it again after refreshing the page.

You can create as many keys as you like.

How to authenticate using the personal API key

There are three options:

1. Use the Authorization header and Bearer authentication, like so:
   JavaScript

   const headers = {
       Authorization: `Bearer ${POSTHOG_PERSONAL_API_KEY}`
   }

2. Put the key in request body, like so:
   JavaScript

   const body = {
       personal_api_key: POSTHOG_PERSONAL_API_KEY
   }

3. Put the key in query string, like so:
   JavaScript

   const url = `https://app.posthog.com/api/event/?personal_api_key=${POSTHOG_PERSONAL_API_KEY}`

Any one of these methods works, but only the value encountered first (in the order above) will be used for authentication.

Rate limiting

Private GET, POST, PATCH, DELETE endpoints are rate limited. Public POST-only endpoints are not rate limited. A rule of thumb for whether rate limits apply is if the personal API key is used for authentication.

There are separate limits for different kinds of resources.

• For all analytics endpoints (such as calculating insights, retrieving persons, or retrieving session recordings), the rate limits are 240/minute and 1200/hour.

• The HogQL query endpoint (/api/project/:id/query) has a rate limit of 120/hour.

• For feature flag local evaluation (which is enabled in SDKs when you input a personal API key), the rate limit is 600/minute.

• For the rest of the create, read, update, and delete endpoints, the rate limits are 480/minute and 4800/hour.

• For Public POST-only endpoints like event capture (/capture) and feature flag evaluation (/decide), there are no rate limits.

These limits apply to the entire team (i.e. all users within your PostHog organization). For example, if a script requesting feature flag metadata hits the rate limit, and another user, using a different personal API key, makes a single request to the persons API, this gets rate limited as well.

For large or regular exports of events, use batch exports.

Want to use the PostHog API beyond these limits? Email us at customers@posthog.com.

Pagination

Requests are paginated if the results are higher than the limit, usually 100 (sometimes 500 or 1000). Pagination happens in the following format:

{
  "next": "https://app.posthog.com/api/person/?cursor=cD0yMjgxOTA2",
  "previous": null,
  "results": [
    // ...
  ]
}

You can then just call the "next" URL to get the next set of results.

Tips

• The /users/@me/ endpoint gives you useful information about the current user.

• The /api/event_definition/ and /api/property_definition endpoints provide the possible event names and properties you can use throughout the rest of the API.

• The maximum size of a POST request body is governed by settings.DATA_UPLOAD_MAX_MEMORY_SIZE, and is 20MB by default.

• By default, the PostHog API returns results from the last project you visited in the UI. To override this behavior, you can pass in your project API key as a query parameter in the request like api/event/?token=my_project_api_key.

• You can download the OpenAPI spec (aka API schema) at https://app.posthog.com/api/schema/. (Be sure to be logged in to app.posthog.com.)

• You can view the API schema with Swagger UI at https://app.posthog.com/api/schema/swagger-ui/ (Be sure to be logged in to app.posthog.com.)