API overview

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:

Public POST-only endpoints such as /i/v0/e and /flags are used for capturing events, batching events, updating person or group information, and evaluating feature flags. These don't require authentication, but use your project token to handle the request.
Private GET, POST, PATCH, DELETE endpoints are used for querying, creating, updating, or deleting nearly all 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. On US Cloud, these are https://us.i.posthog.com for public endpoints and https://us.posthog.com for private ones. On EU Cloud, these are https://eu.i.posthog.com for public endpoints and https://eu.posthog.com for private ones. For self-hosted instances, use your self-hosted domain. Confirm yours by checking your PostHog instance URL.

Authentication

Private endpoints require authentication. There are two ways to authenticate, and which one you should use depends on who the integration is for:

Personal API keys – Use these when you're using PostHog from your own scripts, automations, or any integration tied to your own account. This is the right choice if you're just building something for your own project.
OAuth – Use this when you're building an app that other PostHog users will install or connect to. OAuth lets users grant your app scoped access without sharing their personal API key.

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.
For the events/values endpoint, the rate limits are 60/minute and 300/hour. When using a personal API key, the event_name query parameter is required. For queries without event filters, use the query endpoint instead.
The query endpoint has a rate limit of 2400/hour. For large or regular exports of events, use batch exports. For data-powered APIs or user-facing dashboards, reach out to us.
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 (/i/v0/e) and feature flag evaluation (/flags), 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.

At this time, we are not offering higher limits than these, but you may wish to try our endpoints product, which offers query customization and higher limits. Alternatively, you may be able to use our batch exports product to pull the data that you need from our events or persons tables on a faster cadence.

Responses

Status code: 200

Response:

JSON
{
  "status": "Ok"
}

Meaning: A 200: OK response means we have successfully received the payload, it is in the correct format, and the project token (token) is valid. It does not imply that events are valid and will be ingested. As mentioned in invalid events, certain event validation errors may cause an event not to be ingested.

Status code: 400

Responses:

JSON
{
  "type": "validation_error",
  "code": "invalid_project",
  "detail": "Invalid Project ID.",
  "attr": "project_id"
}

Meaning: We were unable to determine the project to associate the events with.

JSON
{
  "type": "validation_error",
  "code": "invalid_payload",
  "detail": "Malformed request data",
  "attr": null
}

Meaning: Request payload data formatted incorrectly.

Status code: 401

Responses:

JSON
{
  "type": "authentication_error",
  "code": "invalid_api_key",
  "detail": "Project token invalid. You can find your project token in your PostHog project settings."
}

Meaning: The project token you provided is invalid.

JSON
{
  "type": "authentication_error",
  "code": "invalid_personal_api_key",
  "detail": "Invalid Personal API key."
}

Meaning: The personal API key you used for authentication is invalid.

Status code: 503 (Deprecated)

Response:

JSON
{
  "type": "server_error",
  "code": "fetch_team_fail",
  "detail": "Unable to fetch team from database."
}

Meaning: (Deprecated) This error only occurs in self-hosted Postgres instances if the database becomes unavailable. On ClickHouse-backed instances database failures cause events to be added to a dead letter queue, from which they can be recovered.

Pagination

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

JSON
{
  "next": "<ph_app_host>/api/person/?cursor=cD0yMjgxOTA2",
  "previous": null,
  "results": [
    // ...
  ]
}

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

Tips

When logged in, you can view and download the API schema using the following options:
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 token as a query parameter in the request like api/event/?token=my_project_token.

GitHub secret scanning

PostHog partners with GitHub to automatically detect exposed API keys in public repositories. When GitHub detects a leaked key, we take immediate action:

Personal API keys (phx_): The key is automatically rolled and the user is notified via email.
Feature flags secure API keys (phs_): Project admins and owners are notified via email so they can rotate the key.
OAuth access tokens (pha_): The key and its associated refresh token are automatically revoked and the user is notified via email.
OAuth refresh tokens (phr_): The key and its associated access token are automatically revoked and the user is notified via email.

This provides an automatic layer of protection, but you should still follow best practices: never commit API keys to version control, use environment variables, and rotate keys if you suspect exposure.