Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

28.2 KB
Raw Blame

API

Every request goes through src/api/client.ts: it prefixes the host, adds the bearer token, sets X-PostHog-Client-Platform: mobile, refreshes the token once on a 401, and represents HTTP failures as ApiError with the server's code and detail. projectPath('signals/reports/') builds /api/projects/{projectId}/signals/reports/. Streams use apiStream (expo's fetch, so the body streams on native) and src/api/sse.ts.

Ordinary API requests have a 30-second deadline across token refresh and body reads. Caller cancellation stays distinct from a deadline, and neither a timeout nor a lost connection automatically retries a write. A write can reach the server before its response is lost, so a timeout does not mean it failed on the server. Long-lived task streams use their own idle watchdog and reconnect policy. Transport failures have a dedicated error type; unrelated programming errors are not reported as connectivity failures.

The classic conversation transport uses a 30-second connection deadline and a 60-second inactivity deadline. Each received chunk, including a heartbeat, resets the inactivity deadline. An interrupted accepted reply offers reconnection; the app does not resend it automatically. History reconciliation retains streamed generation failures. Pending approvals and clarification forms pause reconnection until the person responds. The classic chat hook exposes form questions from both streamed replies and history, with submit and dismiss methods. Form responses send no new chat message; they resume the conversation with the selected answers or a dismissal. Notebook artifacts retain their Markdown and chart blocks, with links to saved notebooks and a web fallback for other content. Reply links without a project prefix use the conversation's project; explicit project links and external links keep their destination. Canceling a classic reply requires conversation:write for OAuth and personal API tokens.

Most existing types are written by hand per module and name the Django serializer they mirror. PR checks use PullRequestChecksResponseApi from the Signals generated schemas. New API types should come from the generated schemas; update the Django serializer and run hogli build:openapi when those contracts change. Mobile CI includes the Signals schema file for typechecking, and its type-only import adds nothing to the native bundle.

Inbox pages validate the fields used to render report rows before they enter the query cache. A malformed page fails the request while previously loaded pages remain visible. The load-more retry requests the failed page again.

Domain Module Endpoints Notes
Account src/api/users.ts GET /api/users/@me/, GET /api/organizations/{id}/ Account and organization membership
OAuth src/auth/oauth.ts /oauth/authorize, /oauth/token, /oauth/revoke PKCE public client
Inbox and reports src/api/reports.ts signals/reports/?view=for_you&sort=priority, .../{id}/, .../signals/, .../artefacts/, read_state/, .../state/, .../reviewers/, available_reviewers/ DATA.md
Today src/api/today.ts today/reports/{id}/page/ 403 or 404 means the project lacks Today; the report screen shows signals instead
Tasks src/api/tasks.ts tasks/, tasks/{id}/ (PATCH { archived } archives a chat), tasks/{id}/run/ (a chat's resume adds resume_from_run_id and pending_user_message; pending_user_artifact_ids carries staged files), .../runs/{runId}/, .../logs/, .../stream/, .../command/ (user_message, with artifact_ids for files; set_config_option, permission_response, cancel) HANDOFF.md, CHAT.md
Classic AI src/api/conversations.ts GET conversations/, GET conversations/{id}/, POST conversations/ (SSE), PATCH conversations/{id}/cancel/ CHAT.md
Chat attachments src/api/tasks.ts, src/features/chat/attachments/uploadAttachments.ts tasks/{id}/staged_artifacts/prepare_upload/, tasks/{id}/staged_artifacts/finalize_upload/, .../runs/{runId}/artifacts/prepare_upload/, .../runs/{runId}/artifacts/finalize_upload/, all task:write; then a presigned S3 POST with no PostHog auth CHAT.md
Push src/api/pushTokens.ts /api/users/@me/push_tokens/, .../unregister/ PUSH.md
Views pins src/api/shortcuts.ts file_system_shortcut/, .../{id}/ VIEWS.md
Views dashboards src/api/dashboards.ts dashboards/, dashboards/{id}/?refresh=force_cache VIEWS.md
Views insights src/api/insights.ts insights/, insights/{id}/, insights/viewed/ VIEWS.md
Web analytics, people at a point src/api/webAnalytics.ts, src/api/actors.ts query/ (WebOverviewQuery, ActorsQuery) VIEWS.md
Session replay src/api/recordings.ts, src/api/replayVision.ts session_recordings/, query/ (HogQLQuery), vision/observations/, vision/scanners/watch_feed/, vision/scanners/inline_scan/ Session replay

send() also keeps the server clock offset from each response's Date header (src/api/serverClock.ts) and spends a token from the request's budget family (src/api/budget.ts); an empty bucket throws BudgetExceededError without sending.

runQuery() applies one deadline to the initial POST query/ and every status poll. If the server does not answer in time, the request is canceled and the caller gets a timeout error. Reviewer edits load artefact pages until the latest reviewer assignment is found before sending the replacement list, so GitHub-only reviewers remain assigned.

OAuth scopes the app requests: OAUTH_SCOPES in src/auth/oauth.ts.

Error tracking and replay scopes

The app asks for five more scopes for the Errors and Sessions screens. Views, the inbox and chats never need them.

Scope Why
error_tracking:read The issues list, one issue, its events and spikes (error_tracking/query/..., error_tracking/issues/{id}/).
error_tracking:write Resolve, suppress, reopen and assign an issue. It also covers the read.
session_recording:read The sessions list and one recording's metadata and events (session_recordings/).
replay_scanner:read The AI summary and chapters of a recording (vision/observations/).
replay_scanner:write Asking for a summary from the phone (vision/scanners/inline_scan/).

session_recording:write is never requested: the phone does not change or delete recordings. ERRORS_SCOPES and REPLAY_SCOPES in src/api/scopeErrors.ts hold the same lists, and useFeatureAccess('errors' | 'replay') reads them. A server that drops a scope (the OAuth application's ceiling) gets the feature's "isn't available yet" state, not a broken screen.

Error tracking

src/api/errorTracking.ts imports the generated issue-list request and response types. Other reads name the serializers in products/error_tracking/backend/presentation/views/ (query_serializers.py, issues.py, spike_events.py). Mobile CI checks out the Signals and Error Tracking generated schemas. The compact error_tracking/query/ endpoints are the ones the MCP tools and agents use: they wrap ErrorTrackingQuery, EventsQuery and ErrorTrackingBreakdownsQuery and answer typed, small payloads, so the phone does not post raw HogQL queries to query/.

Call Endpoint Scope Payload the app sends or reads
Issues list POST error_tracking/query/issues/ error_tracking:read { dateRange: { date_from: '-24h' | '-7d' }, status: 'active', orderBy: 'users', orderDirection: 'DESC', limit: 15, offset: 0, volumeResolution: 0, assignee?: { type: 'user', id } }; rows carry id, name, description (300 characters at most), status, first_seen, last_seen, library, assignee { id, type }, aggregations { users, occurrences, sessions }. Load more follows nextOffset while hasMore is true
Spikes GET error_tracking/spike_events/?issue_ids=a,b&date_from=<ISO>&limit=100 error_tracking:read results[].issue.id, detected_at; the web's issue list uses the same read for its spike marks
One issue GET error_tracking/issues/{id}/ error_tracking:read id, status, name, description, first_seen, assignee
Impact and chart POST error_tracking/query/issue/ error_tracking:read { issueId, dateRange, includeSparkline: true, volumeResolution: 24 | 28 }; reads impact, sparkline, trend.direction, trend.change_percent, last_seen, library, latest_release, first_release
Where it breaks The same endpoint with includeBreakdown: true error_tracking:read breakdown.occurrences and breakdown.top_values (path, url, screen, browser, os, app_version). Its own request, because the server fails the whole response when the breakdown fails
Frames and sessions POST error_tracking/query/issue_events/ error_tracking:read { issueId, dateRange, limit: 10, include: ['exception', 'stacktrace', 'environment', 'correlation'], onlyAppFrames: true }; reads $exception_list[].stacktrace.frames (already symbolicated at ingestion: resolved_name, source, line), $session_id, $browser, $os, timestamp
Linked report GET signals/reports/?source_product=error_tracking&source_id={id}&limit=1&include_source_metadata=false task:read Error tracking signals carry the issue id as source_id
Status PATCH error_tracking/issues/{id}/ { status: 'active' | 'resolved' | 'suppressed' } error_tracking:write Answers the issue resource
Assign PATCH error_tracking/issues/{id}/assign/ { assignee: { type: 'user', id } | null } error_tracking:write id is the numeric user id from @me

None of these paths is in a src/api/budget.ts family, and none returns a next_allowed_client_refresh hint, so the screens rely on TanStack staleness (60 seconds) and pull to refresh. Pull to refresh discards later pages and reloads the first page. Spike reads are scoped to each loaded page, so loading another page does not repeat the spike lookup for previous pages. New and Spiking filter the loaded rows; an empty partial result offers Load more instead of claiming there are no matching issues in the project. The Spiking filter waits for pending spike lookups and offers a retry when they fail. List sparklines are omitted; the issue detail still requests its chart. A 403 that names a missing scope goes to reportScopeError(error, 'errors'), and the screen shows ViewsReauthState. error_tracking/stack_frames/batch_get/ is not called: the frames in $exception_list already carry resolved names, and the phone shows no code context.

Session replay

src/api/recordings.ts and src/api/replayVision.ts. Types are written by hand and name the serializers they mirror: SessionRecordingSerializer in posthog/session_recordings/session_recording_api.py, and ReplayObservationSerializer, InlineScanResponseSerializer and WatchFeedResponseSerializer in products/replay_vision/backend/api/. The summary's model_output follows SummarizerOutput in products/replay_vision/backend/temporal/scanners/summarizer.py.

Call Endpoint Scope Payload the app sends or reads
Sessions list GET session_recordings/?limit=10&date_from=-7d session_recording:read Newest first (the server's default start_time order). Reads id, distinct_id, recording_duration, start_time, end_time, click_count, console_error_count, start_url, person { name, distinct_ids, properties }, ongoing, activity_score. Load more sends next_cursor as after while has_next is true
Worth watching GET vision/scanners/watch_feed/?limit=5&date_from=-7d replay_scanner:read, session_recording:read results[].observation and results[].reason. Starts after recordings load and never blocks their display. Enriches existing rows in place; other recommendations appear below the recordings without reordering them
One recording GET session_recordings/{id}/ session_recording:read The same fields. A 404 means the recording expired or never existed
Events timeline Two POST query/ with a HogQLQuery, on the replay budget in src/api/budget.ts query:read One for $pageview, $screen and $autocapture clicks (LIMIT 300), one for $rageclick and $exception (LIMIT 100), each where properties.$session_id = {session_id}, between the recording's start and end padded by a minute, ORDER BY timestamp. The session id and the window are values, never query text. Reads the timestamp, the event, $current_url, $pathname, $screen_name, elements_chain_texts, $exception_issue_id, $exception_types, $exception_values, $browser, $os, $geoip_city_name
Summary and chapters GET vision/observations/?session_id={id} replay_scanner:read, session_recording:read Every scanner's observations of the session, newest first. The app uses the newest succeeded summarizer: model_output.title, summary, chapters[] { kind, start_ms, end_ms, title }, key_moment_ms, notability, notability_reason, plus media[] { kind, position } and completed_at. A pending or running summarizer means a summary is on its way
Frame GET vision/observations/{id}/thumbnail/?chapter={n} replay_scanner:read, session_recording:read A 302 to a signed object-storage URL. The app sends redirect: 'manual' and reads Location, so the bearer token never reaches the storage host; the image loads from the signed URL. Without chapter it is the observation's thumbnail
Summarize POST vision/scanners/inline_scan/ { built_in: 'summarize_recording', session_ids: [id] } replay_scanner:write, session_recording:read The web's Summarize button sends the same body, so both share one result. Answers 202 with results[].scan_outcome: started, already_running, already_scanned, skipped_limit, skipped_quota, skipped_scanner_limit or failed. A 400 means the organization has not approved AI data processing

Session pagination deduplicates recording IDs. Pull to refresh reloads the first page and the optional feed. A failed next page preserves the loaded rows and offers Try again.

After started or already_running the screen reloads the observations every 5 seconds while it is focused and the app is in front, for at most 2 minutes. The app never sends PATCH session_recordings/{id}/ (viewed), because that needs session_recording:write, so opening a session on the phone does not mark it watched on the web. A 403 that names a missing scope goes to reportScopeError(error, 'replay'), and the screen shows ViewsReauthState. The timeline's queries spend the replay budget family (runQuery({ budgetFamily: 'replay' }), the same buckets as query), not the Views query family, so Views refreshes and a session screen never block each other.