references/flask.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Flask
Canonical URL: https://posthog.com/docs/libraries/flask
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install with the wizard
- Installation
- Identifying users
- Request contexts
- Error tracking
- Next steps
- Supported versions
PostHog makes it easy to get data about traffic and usage of your Flask app. Integrating PostHog enables analytics, custom events capture, feature flags, error tracking, and more.
This guide walks you through integrating PostHog into your Flask app using the Python SDK.
These docs cover version
7.xof the Python SDK, which requires Python 3.10 or higher. On Python 3.9? See supported versions.
Install with the wizard
Run this command in your project directory to add PostHog to your Flask project. The wizard detects your framework, installs the SDK, and sets up your first events.
npx @posthog/wizard
Or set it up manually by following the rest of this guide.
Installation
To start, run pip install posthog to install PostHog’s Python SDK.
Then, initialize PostHog where you'd like to use it. For example, here's how to capture an event in a simple route:
app.py
from flask import Flask
from posthog import Posthog
app = Flask(__name__)
posthog = Posthog(
'<ph_project_token>',
host='https://us.i.posthog.com',
)
@app.route('/api/dashboard', methods=['POST'])
def api_dashboard():
posthog.capture(
'dashboard_api_called',
distinct_id='distinct_id_of_your_user',
)
return '', 204
You can find your project token and instance address in your project settings.
Identifying users
Identifying users is required. Backend events need a
distinct_idto associate events with the correct user.In Python, you can do this through a context. All event captures in the same context will be tagged automatically with the correct
distinct_id. Typically, you would set a fresh context and identify at the top of each route.from posthog import new_context, identify_context, capture @app.get("/foo") def foo(current_user: User = Depends(get_current_user)): with new_context(): # Set context at the top of a route identify_context(current_user.id) capture("foo_viewed") return {"status": "ok"}When possible, write a small piece of middleware that resolves your authenticated user, wrap a context around the request, and identifies it. Every
capture()downstream is then attributed automatically. The SDK's Django middleware does this automatically and you can replicate it when using the plain Python SDK.
Request contexts
Version 7.69.0 and later of the Python SDK includes a Flask integration that creates a fresh context for every request. It adds the request URL, method, path, route, IP address, and user agent to events captured during the request.
Register the integration after you create your Flask app and PostHog client:
app.py
from posthog.integrations.flask import PosthogFlaskIntegration
PosthogFlaskIntegration(
app,
client=posthog,
capture_exceptions=True,
)
Setting capture_exceptions=True captures unhandled Flask exceptions. Set it to False for request enrichment without automatic exception capture. If you omit it, the integration inherits the client's enable_exception_autocapture setting.
You can also provide:
request_filterto skip both enrichment and automatic exception capture for selected requestsextra_propertiesto add application-specific properties to the request contexttrust_tracing_headersto accept PostHog session and distinct ID headers
If you're using PostHog JavaScript Web on the frontend, configure tracing_headers for your Flask backend hostname so browser requests include the session and distinct ID headers.
The integration ignores these headers by default because clients can control them. Set trust_tracing_headers=True when registering the integration to accept them as analytics context. Don't use them for authentication or authorization.
Identify the request context from your route when you have an authenticated user ID:
from flask import session
from posthog import identify_context
@app.route("/api/dashboard", methods=["POST"])
def api_dashboard():
user_id = session.get("user_id")
if user_id:
identify_context(str(user_id))
posthog.capture("dashboard_api_called")
return "", 204
Events captured without a context or explicit distinct_id are sent as anonymous events with an auto-generated distinct_id. See the Python SDK docs for more details.
Error tracking
PosthogFlaskIntegration captures unhandled exceptions when you set capture_exceptions=True or enable exception autocapture on its client. It doesn't capture expected HTTP exceptions or exceptions consumed by your application's error handlers.
Call capture_exception() from a custom error handler when you want to report a handled exception:
from flask import Flask, jsonify
from posthog import Posthog
app = Flask(__name__)
posthog = Posthog('<ph_project_token>', host='https://us.i.posthog.com')
@app.errorhandler(Exception)
def handle_exception(e):
# Capture methods, including capture_exception, return the UUID of the captured event,
# which you can use to find specific errors users encountered
event_id = posthog.capture_exception(e)
# You can show the event ID to your user, and ask them to include it in bug reports
response = jsonify({'message': str(e), 'error_id': event_id})
response.status_code = 500
return response
Next steps
For any technical questions for how to integrate specific PostHog features into Flask (such as analytics, feature flags, A/B testing, etc.), have a look at our Python SDK docs.
Alternatively, the following tutorials can help you get started:
- How to set up analytics in Python and Flask
- How to set up feature flags in Python and Flask
- How to set up A/B tests in Python and Flask
Supported versions
These docs cover version 7.x of the PostHog Python SDK, which requires Python 3.10 or higher. Python 3.9 is no longer supported on 7.x.x and higher — pin to the 6.x line with pip install 'posthog<7', where 6.9.3 is the final release.
Everything on this page works the same way on 6.9.3. Event capture, the context API (new_context, identify_context, set_context_session), and PosthogContextMiddleware are identical on 6.9.3 and 7.0.0 — 7.0.0 only dropped Python 3.9 and bumped the optional LLM provider SDKs. That includes the middleware identifying the request context from the X-POSTHOG-DISTINCT-ID header and falling back to the authenticated user, which behaves the same across both lines.
Later 7.x releases add what the 6.x line does not receive, such as the Celery integration, tracing header sanitization, and set_context_device_id. They also changed the middleware's own captured properties: 7.x sends the request IP as $ip, where 6.9.3 sends it as $ip_address, and 7.x additionally captures $request_path, $raw_user_agent, and the authenticated user's email.