Skip to main content
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

​
project_id
string
required
The ID of your PostHog project.

​
Query Parameters

​
event
string
Filter events by event name. Example: user_sign_up or $pageview.
​
distinct_id
string
Filter events by a specific distinct ID (user identifier).
​
person_id
integer
Filter events by PostHog person ID.
​
before
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)
​
after
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)
​
limit
integer
default:"100"
Maximum number of results to return. Maximum value: 10,000.
​
offset
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.
​
properties
json
Filter events by property values. Provide as URL-encoded JSON.Example: properties=[{"key":"$browser","value":"Chrome"}]
​
orderBy
json
Order results by fields. Defaults to ["-timestamp"] (newest first).Example: orderBy=["timestamp"] for oldest first.
​
select
json
(Experimental) Specify which fields to return using HogQL expressions.
​
where
json
(Experimental) Additional HogQL filter expressions.

​
Response

​
results
array
Array of event objects.
​
id
string
Unique event UUID.
​
event
string
Event name.
​
distinct_id
string
The distinct ID associated with this event.
​
properties
object
Event properties as key-value pairs.
​
timestamp
datetime
When the event occurred (ISO 8601 format).
​
person
object
Person information (if available and requested).
​
id
integer
Person ID.
​
name
string
Person’s display name.
​
distinct_ids
array
All distinct IDs associated with this person.
​
properties
object
Person properties.
​
elements
array
DOM elements associated with the event (for autocapture events).
​
next
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>"

​
Pagination

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

  1. Initial request returns up to limit events
  2. If more events exist, next contains a URL with before or after parameter
  3. Request the next URL to get the next page
  4. 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>"

​
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:
  1. Starts with a small time window (1 minute)
  2. Progressively expands if insufficient results are found
  3. Caches successful window sizes for future requests
This optimization happens automatically and improves performance for recent event queries.

​
Best Practices

  1. Always specify time range: Use after and before to limit the data scanned
  2. Use appropriate limits: Don’t request more data than needed
  3. Filter early: Apply event and distinct_id filters to reduce result sets
  4. Use timestamp pagination: Avoid offset-based pagination for large datasets
  5. 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
    }
)
The Query endpoint offers:
  • Better performance for complex queries
  • More powerful filtering with HogQL
  • Aggregation capabilities
  • Better caching
  • Lower rate limits

Build docs developers (and LLMs) love

Get started for freeTalk to us