List Events

This endpoint is effectively deprecated. For querying and analyzing events, use the Query endpoint instead. For bulk event exports, use PostHog’s CDP or Batch Exports features.

The List Events endpoint allows you to retrieve a paginated list of events with basic filtering capabilities.

Endpoint

GET /api/projects/:project_id/events

Authentication

Use a Personal API Key in the Authorization header:

Authorization: Bearer <your_personal_api_key>

Path Parameters

string

required

The ID of your PostHog project.

Query Parameters

string

Filter events by event name. Example: user_sign_up or $pageview.

string

Filter events by a specific distinct ID (user identifier).

integer

Filter events by PostHog person ID.

datetime

Return only events with a timestamp before this time. Defaults to now() + 5 seconds.Format: ISO 8601 datetime (e.g., 2024-03-15T14:30:00Z)

datetime

Return only events with a timestamp after this time. Defaults to now() - 24 hours.Format: ISO 8601 datetime (e.g., 2024-03-15T14:30:00Z)

integer

default:"100"

Maximum number of results to return. Maximum value: 10,000.

integer

deprecated

Number of results to skip. Deprecated: Use timestamp-based pagination instead.

Offset-based pagination is deprecated and will fail for values larger than 50,000. Use before/after parameters for timestamp-based pagination.

json

Filter events by property values. Provide as URL-encoded JSON.Example: properties=[{"key":"$browser","value":"Chrome"}]

json

Order results by fields. Defaults to ["-timestamp"] (newest first).Example: orderBy=["timestamp"] for oldest first.

json

(Experimental) Specify which fields to return using HogQL expressions.

json

(Experimental) Additional HogQL filter expressions.

Response

array

Array of event objects.

string

Unique event UUID.

string

Event name.

string

The distinct ID associated with this event.

object

Event properties as key-value pairs.

datetime

When the event occurred (ISO 8601 format).

object

Person information (if available and requested).

integer

Person ID.

string

Person’s display name.

array

All distinct IDs associated with this person.

object

Person properties.

array

DOM elements associated with the event (for autocapture events).

string

URL for the next page of results. null if no more results.

Examples

curl -X GET "https://app.posthog.com/api/projects/12345/events?limit=10" \
  -H "Authorization: Bearer <your_personal_api_key>"

curl -X GET "https://app.posthog.com/api/projects/12345/events?event=button_clicked&limit=20" \
  -H "Authorization: Bearer <your_personal_api_key>"

curl -X GET "https://app.posthog.com/api/projects/12345/events?distinct_id=user_123&limit=50" \
  -H "Authorization: Bearer <your_personal_api_key>"

curl -X GET "https://app.posthog.com/api/projects/12345/events?after=2024-03-01T00:00:00Z&before=2024-03-15T23:59:59Z" \
  -H "Authorization: Bearer <your_personal_api_key>"

curl -X GET "https://app.posthog.com/api/projects/12345/events?properties=%5B%7B%22key%22%3A%22%24browser%22%2C%22value%22%3A%22Chrome%22%7D%5D" \
  -H "Authorization: Bearer <your_personal_api_key>"

import requests
from urllib.parse import urlencode

url = "https://app.posthog.com/api/projects/12345/events"
headers = {"Authorization": "Bearer <your_personal_api_key>"}

params = {
    "event": "user_signed_up",
    "after": "2024-03-01T00:00:00Z",
    "limit": 100
}

response = requests.get(url, headers=headers, params=params)
events = response.json()

for event in events["results"]:
    print(f"{event['timestamp']}: {event['event']} by {event['distinct_id']}")

const axios = require('axios');

const url = 'https://app.posthog.com/api/projects/12345/events';
const headers = {
  'Authorization': 'Bearer <your_personal_api_key>'
};

const params = {
  event: 'button_clicked',
  limit: 50
};

axios.get(url, { headers, params })
  .then(response => {
    const events = response.data;
    events.results.forEach(event => {
      console.log(`${event.timestamp}: ${event.event}`);
    });
  })
  .catch(error => console.error('Error:', error));

Pagination

Timestamp-based Pagination (Recommended)

Use the before and after parameters with the next URL from the response:

import requests

url = "https://app.posthog.com/api/projects/12345/events"
headers = {"Authorization": "Bearer <your_personal_api_key>"}
params = {"limit": 100}

all_events = []

while True:
    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    
    all_events.extend(data["results"])
    
    if not data["next"]:
        break
    
    # Use the next URL provided in the response
    url = data["next"]
    params = {}  # Parameters are included in the next URL

print(f"Retrieved {len(all_events)} total events")

How It Works

Initial request returns up to limit events
If more events exist, next contains a URL with before or after parameter
Request the next URL to get the next page
Repeat until next is null

The next URL automatically includes the appropriate before or after timestamp based on your sort order.

Retrieve Single Event

To retrieve a specific event by its UUID:

GET /api/projects/:project_id/events/:event_id

curl -X GET "https://app.posthog.com/api/projects/12345/events/018f1b2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b" \
  -H "Authorization: Bearer <your_personal_api_key>"

curl -X GET "https://app.posthog.com/api/projects/12345/events/018f1b2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b?include_person=true" \
  -H "Authorization: Bearer <your_personal_api_key>"

Rate Limiting

The Events List endpoint is subject to rate limiting:

Burst rate: 240 requests per minute
Sustained rate: 480 requests per hour

If you exceed these limits, you’ll receive a 429 Too Many Requests response.

Performance Considerations

Time Windows

PostHog automatically optimizes queries using progressive time windows. The API:

Starts with a small time window (1 minute)
Progressively expands if insufficient results are found
Caches successful window sizes for future requests

This optimization happens automatically and improves performance for recent event queries.

Best Practices

Always specify time range: Use after and before to limit the data scanned
Use appropriate limits: Don’t request more data than needed
Filter early: Apply event and distinct_id filters to reduce result sets
Use timestamp pagination: Avoid offset-based pagination for large datasets
Consider the Query endpoint: For complex analysis, use /api/projects/:id/query instead

CSV Export

Request events in CSV format by setting the Accept header:

curl -X GET "https://app.posthog.com/api/projects/12345/events?event=user_signed_up&limit=1000" \
  -H "Authorization: Bearer <your_personal_api_key>" \
  -H "Accept: text/csv" \
  -o events.csv

CSV exports default to 3,500 events maximum.

Migration to Query Endpoint

If you’re using the List Events endpoint, consider migrating to the Query endpoint for better performance and capabilities:

response = requests.get(
    "https://app.posthog.com/api/projects/12345/events",
    headers={"Authorization": "Bearer <api_key>"},
    params={
        "event": "button_clicked",
        "after": "2024-03-01",
        "limit": 100
    }
)

response = requests.post(
    "https://app.posthog.com/api/projects/12345/query",
    headers={"Authorization": "Bearer <api_key>"},
    json={
        "query": {
            "kind": "EventsQuery",
            "select": ["event", "timestamp", "distinct_id", "properties"],
            "event": "button_clicked",
            "after": "2024-03-01",
            "limit": 100
        }
    }
)

The Query endpoint offers:

Better performance for complex queries
More powerful filtering with HogQL
Aggregation capabilities
Better caching
Lower rate limits

Overview

Events

Feature Flags

Cohorts

Insights

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Examples

How It Works

Retrieve Single Event

Rate Limiting

Performance Considerations

Time Windows

Best Practices

CSV Export

Migration to Query Endpoint

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Response

​Examples

​Pagination

​Timestamp-based Pagination (Recommended)

​How It Works

​Retrieve Single Event

​Rate Limiting

​Performance Considerations

​Time Windows

​Best Practices

​CSV Export

​Migration to Query Endpoint

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Examples

Pagination

Timestamp-based Pagination (Recommended)

How It Works

Retrieve Single Event

Rate Limiting

Performance Considerations

Time Windows

Best Practices

CSV Export

Migration to Query Endpoint