API

This section of our Docs explains how to pull or push data from/to our API. PostHog has an API available on all tiers of PostHog cloud pricing, including the free tier, and for every self-hosted version.

Please note that PostHog makes use of two different APIs, serving different purposes and using different mechanisms for authentication.

One API is used for pushing data into PostHog. This uses the 'Team API Key' that is included in the frontend snippet. This API Key is public, and is what we use in our frontend integration to push events into PostHog, as well as to check for feature flags, for instance.

The other API is more powerful and allows you to perform any action as if you were an authenticated user utilizing the PostHog UI. It is mostly used for getting data out of PostHog, as well as other private actions such as creating a feature flag. This uses a 'Personal API Key' which you need to create manually (instructions below). This API Key is private and you should not make it public nor share it with anyone. It gives you access to all the data held by your PostHog instance, which includes sensitive information.

These API Docs refer mostly to the private API, performing authentication as outlined below. The only exception is the POST-only public endpoints section. This section explicitly informs you on how to perform authentication. For endpoints in all other sections, authentication is done as described below.

Authentication

Personal API keys (Recommended)

Personal API keys allow full access to your account, just like e-mail address and password, but you can create any number of them and each one can invalidated individually at any moment. This makes for greater control for you and improved security of stored data.

How to obtain a personal API key

Click on your name/avatar on the top right.
Click the gear next to your name to access 'Account settings'.
Navigate to the 'Personal API Keys' section.
Click "+ Create a Personal API Key".
Give your new key a label – it's just for you, usually to describe the key's purpose.
Click 'Create Key'.
There you go! At the top of the list you should now be seeing your brand new key. Immediately copy its value, as you'll never see it again after refreshing the page. But don't worry if you forget to copy it – you can delete and create keys as much as you want.

How to use a personal API key

There are three options:

Use the Authorization header and Bearer authentication, like so:

JavaScript

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

Put the key in request body, like so:

JavaScript

const body = {
    personal_api_key: POSTHOG_PERSONAL_API_KEY
}

Put the key in query string, like so:

JavaScript

const url = `https://posthog.example.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!

For PostHog Cloud, use app.posthog.com as the host address.

Specifying a project when using the API

By default, if you're accessing the API, PostHog will return results from the last project you visited in the UI. To override this behavior, you can pass in your Project API Key (public token) as a query parameter in the request. This ensures you will get data from the project associated with that token.

Example

api/event/?token=my_project_api_key

cURL example for self-hosted PostHog

Terminal

POSTHOG_PERSONAL_API_KEY=qTjsppKJqYLr2YskbsLXmu46eW1oH0r3jZkmKaERlf0
curl \
--header "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
https://posthog.example.com/api/person/

cURL example for PostHog Cloud

Terminal

POSTHOG_PERSONAL_API_KEY=qTjsppKJqYLr2YskbsLXmu46eW1oH0r3jZkmKaERlf0
curl \
--header "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
https://app.posthog.com/api/person/

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.

Pagination

Sometimes requests are paginated. If that's the case, it'll be in the following format:

JSON

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

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

Rate limiting

All requests to PostHog, except for evaluating feature flags and sending events (i.e. the POST-only public endpoints), are rate limited.

In practice, a rule of thumb for whether rate limits apply or not is to check if a personal API key is used for auth. Everything using a personal API key for auth is rate limited.

There's separate limits for different kinds of resources.

For all CRUD endpoints, the rate limits are 480/minute and 4800/hour.

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

Note that these limits apply to the entire team, so if you have a feature-flag requesting script that hits the rate limit, and another user, using a different API key, makes just a single request to the persons API, this would get rate limited as well.

For large or regular exports of events we would recommend using export apps.

If want to use the PostHog API beyond these limits (for example by using PostHog to power your user-facing dashboards) then please email us at customers@posthog.com.

Contributing to API docs

API docs are generated using drf-spectacular. It looks at the Django models and djangorestframework serializers.

Note: We don't automatically add new API endpoints to the sidebar, so you'll need to add those to sidebar.json

You can add a help_text="Field that does x" attribute to any Model or Serializer field to help users understand what a specific field is used for:

Python

class Insight(models.Model):
    last_refresh: models.DateTimeField = models.DateTimeField(blank=True, null=True, help_text="When the cache for the result of this insight was last refreshed.")

class InsightSerializer(TaggedItemSerializerMixin, InsightBasicSerializer):
    filters_hash = serializers.CharField(
        read_only=True,
        help_text="A hash of the filters that generate this insight.",
    )

To add a description to the top of a page, add a comment to the viewset class:

Python

class InsightViewSet(TaggedItemViewSetMixin, StructuredViewSetMixin, viewsets.ModelViewSet):
    """
    Stores saved insights along with their entire configuration options. Saved insights can be stored as standalone
    reports or part of a dashboard.
    """

You can do the same thing for specific endpoints.

Python

@action(methods=["GET", "POST"], detail=False)
def trend(self, request: request.Request, *args: Any, **kwargs: Any) -> Response:
    """
    Test comment, which [even supports markdown](https://example.com)
    """

To check what any changes will roughly look like locally, you can go to http://127.0.0.1:8000/api/schema/redoc/.

Insights serializer

The serializer for insight lives here. Each time an insight gets created we check it against these serializers, and we'll send an error to Sentry (but not the user) if it doesn't match, to ensure the API docs are up to date.

Documenting custom endpoints

If you have an @action endpoint or a custom endpoint (that doesn't use DRF) you can still document by providing a serializer for the request and response.

Python

from drf_spectacular.utils import OpenApiResponse
from posthog.api.documentation import extend_schema
@extend_schema(
    request=FunnelSerializer,
    responses=OpenApiResponse(
        response=FunnelStepsResultsSerializer,
        description="Note, if funnel_viz_type is set the response will be different.",
     ),
    methods=["POST"],
    tags=["funnel"],
    operation_id="Funnels",
)
@action(methods=["GET", "POST"], detail=False)
def funnel(self, request: request.Request, *args: Any, **kwargs: Any) -> Response:

Testing API docs locally

To test or develop the API docs locally, you need to create a personal API key (see top of this page) and then export it before running gatsby, in the same terminal window:

Terminal