openapi: 3.0.3 info: title: PostHog actions sdk_doctor API version: 1.0.0 description: '' tags: - name: sdk_doctor paths: /api/projects/{project_id}/sdk_doctor/report/: get: operationId: sdk_doctor_report_retrieve description: Returns a pre-digested health assessment of the PostHog SDKs the project is using. Covers which SDKs are current vs outdated (smart-semver rules with grace periods and traffic-percentage thresholds), per-version breakdown, and a human-readable reason for each assessment. Use this to diagnose SDK version issues, surface upgrade recommendations, or check overall SDK health. summary: Get SDK health report for a project parameters: - in: query name: force_refresh schema: type: boolean description: When true, bypasses the Redis cache and re-queries ClickHouse for SDK usage. Use sparingly — data is refreshed every 12 hours by a background job. - $ref: '#/components/parameters/ProjectIdPath' tags: - sdk_doctor security: - PersonalAPIKeyAuth: - project:read responses: '200': content: application/json: schema: $ref: '#/components/schemas/SdkHealthReport' description: '' x-explicit-tags: - sdk_doctor components: schemas: SdkHealthReport: type: object properties: overall_health: allOf: - $ref: '#/components/schemas/OverallHealthEnum' description: '''healthy'' when no SDKs need updating, ''needs_attention'' otherwise. * `healthy` - healthy * `needs_attention` - needs_attention' health: allOf: - $ref: '#/components/schemas/HealthEnum' description: 'UI-level status — ''success'' when healthy, ''warning'' when some SDKs are outdated, ''danger'' when the majority are outdated. * `success` - success * `warning` - warning * `danger` - danger' needs_updating_count: type: integer description: Number of SDKs that need updating. team_sdk_count: type: integer description: Number of distinct PostHog SDKs the project is actively using. sdks: type: array items: $ref: '#/components/schemas/SdkAssessment' description: Per-SDK health assessments. required: - health - needs_updating_count - overall_health - sdks - team_sdk_count OverallHealthEnum: enum: - healthy - needs_attention type: string description: '* `healthy` - healthy * `needs_attention` - needs_attention' SdkAssessmentSeverityEnum: enum: - none - warning - danger type: string description: '* `none` - none * `warning` - warning * `danger` - danger' OutdatedTrafficAlert: type: object properties: version: type: string description: Outdated version handling significant traffic. threshold_percent: type: number format: double description: Traffic-percentage threshold that triggered the alert (10% for most SDKs, 20% for web). required: - threshold_percent - version SdkAssessment: type: object properties: lib: type: string description: SDK identifier, e.g. 'web', 'posthog-python', 'posthog-node', 'posthog-ios'. readable_name: type: string description: Human-readable SDK name matching the SDK Doctor UI (e.g. 'Python', 'Node.js', 'Web', 'iOS'). latest_version: type: string description: Most recent published version of this SDK. needs_updating: type: boolean description: True if this SDK needs attention (is_outdated OR is_old). is_outdated: type: boolean description: True if the primary in-use version is flagged as outdated. is_old: type: boolean description: True if the primary in-use version is flagged as old by age alone. severity: allOf: - $ref: '#/components/schemas/SdkAssessmentSeverityEnum' description: 'UI severity badge — ''none'' when healthy, ''warning'' when outdated, ''danger'' when the majority of team SDKs are outdated. * `none` - none * `warning` - warning * `danger` - danger' reason: type: string description: Per-SDK programmatic summary (used for ranking/filtering). For user-facing copy, prefer releases[].status_reason (badge tooltip) and banners (top-level alert text) — those match the UI exactly. banners: type: array items: type: string description: Top-level alert sentences matching the SDK Doctor UI's 'Time for an update!' banner — one per outdated version with significant traffic. Quote verbatim when surfacing the headline to users. releases: type: array items: $ref: '#/components/schemas/SdkReleaseAssessment' description: Per-version assessment for all versions seen in the last 7 days. outdated_traffic_alerts: type: array items: $ref: '#/components/schemas/OutdatedTrafficAlert' description: Outdated versions that handle a significant share of traffic (above the threshold). Not populated for mobile SDKs. required: - banners - is_old - is_outdated - latest_version - lib - needs_updating - outdated_traffic_alerts - readable_name - reason - releases - severity HealthEnum: enum: - success - warning - danger type: string description: '* `success` - success * `warning` - warning * `danger` - danger' SdkReleaseAssessment: type: object properties: version: type: string description: In-use SDK version string, e.g. '1.298.0'. count: type: integer description: Number of events captured with this version in the last 7 days. max_timestamp: type: string description: Timestamp of the most recent event seen for this version (ISO 8601). release_date: type: string nullable: true description: When this version was published on GitHub (ISO 8601), or null if unknown. days_since_release: type: integer nullable: true description: Days since this version was released, or null if unknown. released_ago: type: string nullable: true description: Human-readable relative release age matching the UI (e.g. '5 months ago'). Null when release_date is unknown. is_outdated: type: boolean description: True when this version is flagged as outdated by smart-semver rules. is_old: type: boolean description: True when this version is flagged as old by age alone (separate from semver rules). needs_updating: type: boolean description: True if is_outdated OR is_old. is_current_or_newer: type: boolean description: True when this version equals or exceeds the latest known published version. status_reason: type: string description: 'Per-version badge tooltip text matching the SDK Doctor UI exactly. Quote verbatim when reporting to users. Varies by state: ''Released X ago. Upgrade recommended.'' for outdated versions, ''You have the latest available. Click Releases above to check for any since.'' for current versions, or ''Released X ago. Upgrading is a good idea, but it''s not urgent yet.'' for recent-but-behind versions.' sql_query: type: string description: SQL SELECT statement for drilling into events for this SDK version over the last 7 days. Suitable to pass to the execute-sql tool or to display as a copy-paste snippet. activity_page_url: type: string description: Relative URL path (starting with /project/{id}/) for the Activity > Explore page pre-filtered to events captured with this lib and lib_version over the last 7 days. Combine with the user's PostHog host (e.g. us.posthog.com) for a clickable link. required: - activity_page_url - count - days_since_release - is_current_or_newer - is_old - is_outdated - max_timestamp - needs_updating - release_date - released_ago - sql_query - status_reason - version parameters: ProjectIdPath: in: path name: project_id required: true schema: type: string description: Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/. securitySchemes: PersonalAPIKeyAuth: type: http scheme: bearer x-tagGroups: - name: All endpoints tags: - LLM Analytics - actions - activity_log - activity_logs - advanced_activity_logs - alerts - annotations - approval_policies - batch_exports - cdp - change_requests - code - code-invites - cohorts - comments - conversations - core - customer_analytics - customer_journeys - customer_profile_configs - dashboard_templates - dashboards - data_color_themes - data_modeling_jobs - data_warehouse - dataset_items - datasets - desktop_recordings - domains - early_access_feature - early_access_features - elements - endpoints - environments - error_tracking - evaluation_runs - evaluations - event_definitions - event_filter - event_schemas - events - experiment_holdouts - experiment_saved_metrics - experiments - exports - external_data_schemas - external_data_sources - feature_flags - file_system - file_system_shortcut - flag_value - groups - groups_types - health_issues - heatmap_screenshots - heatmaps - hog_flows - hog_function_templates - hog_functions - insight_variables - insights - integrations - invites - js-snippet - legal_documents - lineage - live_debugger_breakpoints - llm_analytics - llm_prompts - llm_skills - logs - managed_viewsets - max - max_tools - mcp_server_installations - mcp_servers - mcp_store - mcp_tools - members - notebooks - oauth_applications - object_media_previews - organizations - persisted_folder - persons - platform_features - plugin_configs - product_analytics - product_tours - project_secret_api_keys - projects - property_definitions - proxy_records - public_hog_function_templates - query - replay - reverse_proxy - role_external_references - roles - sandbox-environments - sandbox_environments - saved - schema_property_groups - sdk_doctor - session_group_summaries - session_recording_playlists - session_recordings - session_summaries - sessions - signals - subscriptions - surveys - taggers - task-automations - task-runs - task_automations - tasks - uploaded_media - user_home_settings - user_interviews - users - visual_review - warehouse_dag - warehouse_model_paths - warehouse_saved_queries - warehouse_saved_query_folders - warehouse_tables - warehouse_view_link - warehouse_view_links - web_analytics - web_experiments - web_vitals - welcome - workflows