PostHog SDK Doctor API

openapi: 3.2.0
info:
  title: PostHog 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:
  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/.
  schemas:
    SdkAssessmentSeverityEnum:
      enum:
      - none
      - warning
      - danger
      type: string
      description: '* `none` - none

        * `warning` - warning

        * `danger` - danger'
    OverallHealthEnum:
      enum:
      - healthy
      - needs_attention
      type: string
      description: '* `healthy` - healthy

        * `needs_attention` - needs_attention'
    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
          - 'null'
          description: When this version was published on GitHub (ISO 8601), or null if unknown.
        days_since_release:
          type:
          - integer
          - 'null'
          description: Days since this version was released, or null if unknown.
        released_ago:
          type:
          - string
          - 'null'
          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
    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
    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
    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'
  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