API overview

PostHog provides a comprehensive REST API for programmatic access to your product analytics data, user management, feature flags, and more.

Base URLs

PostHog Cloud is available in two regions. Use the base URL that matches your deployment:

https://us.posthog.com/api/

https://eu.posthog.com/api/

https://your-instance.com/api/

All API requests must use HTTPS. HTTP requests will be rejected.

Response format

The API returns JSON-formatted responses. Successful requests return a 200 status code along with the requested data.

Success response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 123,
      "name": "Example Project",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Error response

Errors return appropriate HTTP status codes with details:

{
  "type": "validation_error",
  "code": "invalid_input",
  "detail": "Invalid project ID provided",
  "attr": "project_id"
}

Common status codes

Status Code	Description
`200`	Success
`201`	Resource created
`400`	Bad request - check your parameters
`401`	Unauthorized - check your API key
`403`	Forbidden - rate limit exceeded or insufficient permissions
`404`	Resource not found
`429`	Too many requests - you’ve hit a rate limit
`500`	Server error

Pagination

List endpoints return paginated results. The response includes pagination metadata:

{
  "count": 150,
  "next": "https://us.posthog.com/api/projects/123/insights/?offset=100",
  "previous": "https://us.posthog.com/api/projects/123/insights/?offset=0",
  "results": []
}

Use the offset and limit query parameters to navigate:

curl -X GET \
  'https://us.posthog.com/api/projects/123/insights/?offset=100&limit=50' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Making your first request

Here’s a simple example to list your projects:

curl -X GET 'https://us.posthog.com/api/projects/' \
  -H 'Authorization: Bearer YOUR_API_KEY'

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get(
    'https://us.posthog.com/api/projects/',
    headers=headers
)

projects = response.json()
print(projects)

const response = await fetch('https://us.posthog.com/api/projects/', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const projects = await response.json();
console.log(projects);

Replace YOUR_API_KEY with your actual personal API key. Never commit API keys to version control.

API endpoint structure

API endpoints follow a consistent pattern:

https://us.posthog.com/api/projects/{project_id}/{resource}/

For example:

/api/projects/123/insights/ - List insights for project 123
/api/projects/123/feature_flags/ - List feature flags for project 123
/api/projects/123/events/ - Query events for project 123

Some endpoints are scoped to your organization:

https://us.posthog.com/api/organizations/{organization_id}/{resource}/

Overview

Events

Feature Flags

Cohorts

Insights

Base URLs

Response format

Success response

Error response

Common status codes

Making your first request

API endpoint structure

Next steps

Authentication

Rate limits

​Base URLs

​Response format

​Success response

​Error response

​Common status codes

​Pagination

​Making your first request

​API endpoint structure

​Next steps

Authentication

Rate limits

Base URLs

Response format

Success response

Error response

Common status codes

Pagination

Making your first request

API endpoint structure

Next steps