PostHog API — insights

naftiko: 1.0.0-alpha2
info:
  label: PostHog API — insights
  description: 'PostHog API — insights. 46 operations. Lead operation: insights. Self-contained Naftiko capability covering
    one Posthog business surface.'
  tags:
  - Posthog
  - insights
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    POSTHOG_API_KEY: POSTHOG_API_KEY
capability:
  consumes:
  - type: http
    namespace: posthog-insights
    baseUri: ''
    description: PostHog API — insights business capability. Self-contained, no shared references.
    resources:
    - name: api-environments-environment_id-insights
      path: /api/environments/{environment_id}/insights/
      operations:
      - name: environmentsinsightslist
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: basic
          in: query
          type: boolean
          description: Return basic insight metadata only (no results, faster).
        - name: created_by
          in: query
          type: string
          description: JSON-encoded array of user IDs. Only returns insights whose `created_by` is in the list, e.g. `[1,42]`.
        - name: created_date_from
          in: query
          type: string
          description: Filter by `created_at > created_date_from`. Accepts absolute or relative dates.
        - name: created_date_to
          in: query
          type: string
          description: Filter by `created_at < created_date_to`. Accepts absolute or relative dates.
        - name: dashboards
          in: query
          type: string
          description: JSON-encoded array of dashboard IDs. Returns insights attached to every listed dashboard (AND).
        - name: date_from
          in: query
          type: string
          description: Filter by `last_modified_at > date_from`. Accepts absolute dates (`2025-04-23`) or relative strings
            (`-7d`, `-1m`).
        - name: date_to
          in: query
          type: string
          description: Filter by `last_modified_at < date_to`. Accepts absolute dates or relative strings.
        - name: favorited
          in: query
          type: boolean
          description: Include this parameter (any value) to restrict results to insights marked as favorited.
        - name: format
          in: query
          type: string
        - name: insight
          in: query
          type: string
          description: Restrict to a single insight type. `JSON` matches non-wrapper query insights; `SQL` matches HogQL queries.
        - name: last_viewed_date_from
          in: query
          type: string
          description: Filter by `last_viewed_at > last_viewed_date_from`. Accepts absolute or relative dates.
        - name: last_viewed_date_to
          in: query
          type: string
          description: Filter by `last_viewed_at < last_viewed_date_to`. Accepts absolute or relative dates.
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: refresh
          in: query
          type: string
          description: 'Whether to refresh the retrieved insights, how aggressively, and if sync or async:'
        - name: saved
          in: query
          type: boolean
          description: When truthy, restricts results to insights that are saved (or attached to a visible dashboard). When
            falsy, only unsaved insights.
        - name: search
          in: query
          type: string
          description: Case-insensitive substring match across name, derived_name, description, and tag names.
        - name: short_id
          in: query
          type: string
        - name: tags
          in: query
          type: string
          description: JSON-encoded array of tag names. Returns insights with any of the listed tags.
        - name: user
          in: query
          type: boolean
          description: Include this parameter (any value) to restrict results to insights created by the authenticated user.
      - name: environmentsinsightscreate
        method: POST
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-insights-activity
      path: /api/environments/{environment_id}/insights/activity/
      operations:
      - name: environmentsinsightsallactivityretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-environments-environment_id-insights-bulk_update_tags
      path: /api/environments/{environment_id}/insights/bulk_update_tags/
      operations:
      - name: environmentsinsightsbulkupdatetagscreate
        method: POST
        description: Bulk update tags on multiple objects.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-environments-environment_id-insights-cancel
      path: /api/environments/{environment_id}/insights/cancel/
      operations:
      - name: environmentsinsightscancelcreate
        method: POST
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-insights-generate_metadata
      path: /api/environments/{environment_id}/insights/generate_metadata/
      operations:
      - name: environmentsinsightsgeneratemetadatacreate
        method: POST
        description: Generate an AI-suggested name and description for an insight based on its query configuration.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-insights-my_last_viewed
      path: /api/environments/{environment_id}/insights/my_last_viewed/
      operations:
      - name: environmentsinsightsmylastviewedretrieve
        method: GET
        description: Returns basic details about the last 5 insights viewed by this user. Most recently viewed first.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-environments-environment_id-insights-trending
      path: /api/environments/{environment_id}/insights/trending/
      operations:
      - name: environmentsinsightstrendingretrieve
        method: GET
        description: Returns trending insights based on view count in the last N days (default 7).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-environments-environment_id-insights-viewed
      path: /api/environments/{environment_id}/insights/viewed/
      operations:
      - name: environmentsinsightsviewedcreate
        method: POST
        description: Update insight view timestamps.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-insights-id
      path: /api/environments/{environment_id}/insights/{id}/
      operations:
      - name: environmentsinsightsretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: from_dashboard
          in: query
          type: integer
          description: 'Only if loading an insight in the context of a dashboard: The relevant dashboard''s ID.'
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
        - name: refresh
          in: query
          type: string
          description: 'Whether to refresh the insight, how aggresively, and if sync or async:'
      - name: environmentsinsightsupdate
        method: PUT
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentsinsightspartialupdate
        method: PATCH
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: environmentsinsightsdestroy
        method: DELETE
        description: Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
    - name: api-environments-environment_id-insights-id-activity
      path: /api/environments/{environment_id}/insights/{id}/activity/
      operations:
      - name: environmentsinsightsactivityretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this insight.
          required: true
    - name: api-environments-environment_id-insights-id-analyze
      path: /api/environments/{environment_id}/insights/{id}/analyze/
      operations:
      - name: environmentsinsightsanalyzeretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this insight.
          required: true
    - name: api-environments-environment_id-insights-id-suggestions
      path: /api/environments/{environment_id}/insights/{id}/suggestions/
      operations:
      - name: environmentsinsightssuggestionsretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this insight.
          required: true
      - name: environmentsinsightssuggestionscreate
        method: POST
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this insight.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-insights-insight_id-sharing
      path: /api/environments/{environment_id}/insights/{insight_id}/sharing/
      operations:
      - name: environmentsinsightssharinglist
        method: GET
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: integer
          required: true
    - name: api-environments-environment_id-insights-insight_id-sharing-passwords
      path: /api/environments/{environment_id}/insights/{insight_id}/sharing/passwords/
      operations:
      - name: environmentsinsightssharingpasswordscreate
        method: POST
        description: Create a new password for the sharing configuration.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: integer
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-insights-insight_id-sharing-passwords-password_i
      path: /api/environments/{environment_id}/insights/{insight_id}/sharing/passwords/{password_id}/
      operations:
      - name: environmentsinsightssharingpasswordsdestroy
        method: DELETE
        description: Delete a password from the sharing configuration.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: integer
          required: true
        - name: password_id
          in: path
          type: string
          required: true
    - name: api-environments-environment_id-insights-insight_id-sharing-refresh
      path: /api/environments/{environment_id}/insights/{insight_id}/sharing/refresh/
      operations:
      - name: environmentsinsightssharingrefreshcreate
        method: POST
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: integer
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-environments-environment_id-insights-insight_id-thresholds
      path: /api/environments/{environment_id}/insights/{insight_id}/thresholds/
      operations:
      - name: environmentsinsightsthresholdslist
        method: GET
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: insight_id
          in: path
          type: integer
          required: true
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
    - name: api-environments-environment_id-insights-insight_id-thresholds-id
      path: /api/environments/{environment_id}/insights/{insight_id}/thresholds/{id}/
      operations:
      - name: environmentsinsightsthresholdsretrieve
        method: GET
        description: ''
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: A UUID string identifying this threshold.
          required: true
        - name: insight_id
          in: path
          type: integer
          required: true
    - name: api-projects-project_id-insights
      path: /api/projects/{project_id}/insights/
      operations:
      - name: insightslist
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: basic
          in: query
          type: boolean
          description: Return basic insight metadata only (no results, faster).
        - name: created_by
          in: query
          type: string
          description: JSON-encoded array of user IDs. Only returns insights whose `created_by` is in the list, e.g. `[1,42]`.
        - name: created_date_from
          in: query
          type: string
          description: Filter by `created_at > created_date_from`. Accepts absolute or relative dates.
        - name: created_date_to
          in: query
          type: string
          description: Filter by `created_at < created_date_to`. Accepts absolute or relative dates.
        - name: dashboards
          in: query
          type: string
          description: JSON-encoded array of dashboard IDs. Returns insights attached to every listed dashboard (AND).
        - name: date_from
          in: query
          type: string
          description: Filter by `last_modified_at > date_from`. Accepts absolute dates (`2025-04-23`) or relative strings
            (`-7d`, `-1m`).
        - name: date_to
          in: query
          type: string
          description: Filter by `last_modified_at < date_to`. Accepts absolute dates or relative strings.
        - name: favorited
          in: query
          type: boolean
          description: Include this parameter (any value) to restrict results to insights marked as favorited.
        - name: format
          in: query
          type: string
        - name: insight
          in: query
          type: string
          description: Restrict to a single insight type. `JSON` matches non-wrapper query insights; `SQL` matches HogQL queries.
        - name: last_viewed_date_from
          in: query
          type: string
          description: Filter by `last_viewed_at > last_viewed_date_from`. Accepts absolute or relative dates.
        - name: last_viewed_date_to
          in: query
          type: string
          description: Filter by `last_viewed_at < last_viewed_date_to`. Accepts absolute or relative dates.
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: refresh
          in: query
          type: string
          description: 'Whether to refresh the retrieved insights, how aggressively, and if sync or async:'
        - name: saved
          in: query
          type: boolean
          description: When truthy, restricts results to insights that are saved (or attached to a visible dashboard). When
            falsy, only unsaved insights.
        - name: search
          in: query
          type: string
          description: Case-insensitive substring match across name, derived_name, description, and tag names.
        - name: short_id
          in: query
          type: string
        - name: tags
          in: query
          type: string
          description: JSON-encoded array of tag names. Returns insights with any of the listed tags.
        - name: user
          in: query
          type: boolean
          description: Include this parameter (any value) to restrict results to insights created by the authenticated user.
      - name: insightscreate
        method: POST
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-projects-project_id-insights-activity
      path: /api/projects/{project_id}/insights/activity/
      operations:
      - name: insightsallactivityretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-projects-project_id-insights-bulk_update_tags
      path: /api/projects/{project_id}/insights/bulk_update_tags/
      operations:
      - name: insightsbulkupdatetagscreate
        method: POST
        description: Bulk update tags on multiple objects.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-projects-project_id-insights-cancel
      path: /api/projects/{project_id}/insights/cancel/
      operations:
      - name: insightscancelcreate
        method: POST
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-projects-project_id-insights-generate_metadata
      path: /api/projects/{project_id}/insights/generate_metadata/
      operations:
      - name: insightsgeneratemetadatacreate
        method: POST
        description: Generate an AI-suggested name and description for an insight based on its query configuration.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-projects-project_id-insights-my_last_viewed
      path: /api/projects/{project_id}/insights/my_last_viewed/
      operations:
      - name: insightsmylastviewedretrieve
        method: GET
        description: Returns basic details about the last 5 insights viewed by this user. Most recently viewed first.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-projects-project_id-insights-trending
      path: /api/projects/{project_id}/insights/trending/
      operations:
      - name: insightstrendingretrieve
        method: GET
        description: Returns trending insights based on view count in the last N days (default 7).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
    - name: api-projects-project_id-insights-viewed
      path: /api/projects/{project_id}/insights/viewed/
      operations:
      - name: insightsviewedcreate
        method: POST
        description: Update insight view timestamps.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-projects-project_id-insights-id
      path: /api/projects/{project_id}/insights/{id}/
      operations:
      - name: insightsretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: from_dashboard
          in: query
          type: integer
          description: 'Only if loading an insight in the context of a dashboard: The relevant dashboard''s ID.'
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
        - name: refresh
          in: query
          type: string
          description: 'Whether to refresh the insight, how aggresively, and if sync or async:'
      - name: insightsupdate
        method: PUT
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: insightspartialupdate
        method: PATCH
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: insightsdestroy
        method: DELETE
        description: Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: string
          description: Numeric primary key or 8-character `short_id` (for example `AaVQ8Ijw`) identifying the insight.
          required: true
    - name: api-projects-project_id-insights-id-activity
      path: /api/projects/{project_id}/insights/{id}/activity/
      operations:
      - name: insightsactivityretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this insight.
          required: true
    - name: api-projects-project_id-insights-id-analyze
      path: /api/projects/{project_id}/insights/{id}/analyze/
      operations:
      - name: insightsanalyzeretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this insight.
          required: true
    - name: api-projects-project_id-insights-id-suggestions
      path: /api/projects/{project_id}/insights/{id}/suggestions/
      operations:
      - name: insightssuggestionsretrieve
        method: GET
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this insight.
          required: true
      - name: insightssuggestionscreate
        method: POST
        description: DRF ViewSet mixin that gates coalesced responses behind permission checks.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: format
          in: query
          type: string
        - name: id
          in: path
          type: integer
          descripti

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/posthog/refs/heads/main/capabilities/posthog-insights.yaml