• Product
  • Pricing
  • Docs
  • Using PostHog
  • Community
  • Company
  • Login
  • Docs

  • Overview
    • Quickstart with PostHog Cloud
    • Overview
      • AWS
      • Azure
      • DigitalOcean
      • Google Cloud Platform
      • Hobby
      • Other platforms
      • Instance settings
      • Environment variables
      • Securing PostHog
      • Monitoring with Grafana
      • Running behind a proxy
      • Configuring email
      • Helm chart configuration
      • Deploying ClickHouse using Altinity.Cloud
      • Configuring Slack
      • Overview
        • Overview
        • Upgrade notes
        • Overview
        • 0001-events-sample-by
        • 0002_events_sample_by
        • 0003_fill_person_distinct_id2
        • ClickHouse
          • Backup
          • Kafka Engine
          • Resize disk
          • Restore
          • Vertical scaling
          • Horizontal scaling (Sharding & replication)
        • Kafka
          • Resize disk
          • Log retention
        • PostgreSQL
          • Resize disk
          • Troubleshooting long-running migrations
        • Plugin server
        • MinIO
        • Redis
        • Zookeeper
      • Disaster recovery
    • Troubleshooting and FAQs
    • Architecture
    • Managing hosting costs
    • EU-only hosting
    • Overview
    • Ingest live data
    • Ingest historical data
    • Identify users
    • User properties
    • Deploying a reverse proxy
    • Libraries
    • Badge
      • Snippet installation
      • Android
      • iOS
      • JavaScript
      • Flutter
      • React Native
      • Browser Extensions
      • Elixir
      • Go
      • Java
      • Node.js
      • PHP
      • Python
      • Ruby
      • Docusaurus v2
      • Gatsby
      • Google Tag Manager
      • Next.js
      • Nuxt.js
      • Retool
      • RudderStack
      • Segment
      • Sentry
      • Slack
      • Shopify
      • WordPress
      • Message formatting
      • Microsoft Teams
      • Slack
      • Discord
    • To another self-hosted instance
    • To PostHog from Amplitude
    • Between Cloud and self-hosted
    • Overview
    • Troubleshooting
      • Overview
      • Tutorial
      • TypeScript types
      • Developer reference
        • Amazon Kinesis Import
        • BitBucket Release Tracker
        • Braze Import
        • Event Replicator
        • GitHub Release Tracker
        • GitHub Star Sync
        • GitLab Release Tracker
        • Heartbeat
        • Ingestion Alert
        • Email Scoring
        • n8n Connector
        • Orbit Connector
        • Redshift Import
        • Segment Connector
        • Shopify Connector
        • Twitter Followers Tracker
        • Zendesk Connector
        • Airbyte Exporter
        • Amazon S3 Export
        • BigQuery Export
        • Customer.io Connector
        • Databricks Export
        • Engage Connector
        • GCP Pub/Sub Connector
        • Google Cloud Storage Export
        • Hubspot Connector
        • Intercom Connector
        • Migrator 3000
        • PagerDuty Connector
        • PostgreSQL Export
        • Redshift Export
        • RudderStack Export
        • Salesforce Connector
        • Sendgrid Connector
        • Sentry Connector
        • Snowflake Export
        • Twilio Connector
        • Variance Connector
        • Zapier Connector
        • Downsampler
        • Event Sequence Timer
        • First Time Event Tracker
        • Property Filter
        • Property Flattener
        • Schema Enforcer
        • Taxonomy Standardizer
        • Unduplicator
        • Automatic Cohort Creator
        • Currency Normalizer
        • GeoIP Enricher
        • Timestamp Parser
        • URL Normalizer
        • User Agent Populator
    • Overview
    • POST-only public endpoints
    • Actions
    • Annotations
    • Cohorts
    • Dashboards
    • Event definitions
    • Events
    • Experiments
    • Feature flags
    • Funnels
    • Groups
    • Groups types
    • Insights
    • Invites
    • Members
    • Persons
    • Plugin configs
    • Plugins
    • Projects
    • Property definitions
    • Session recordings
    • Trends
    • Users
    • Data model
    • Overview
    • GDPR guidance
    • HIPAA guidance
    • CCPA guidance
    • Data egress & compliance
    • Overview
    • Code of conduct
    • Recognizing contributions
  • Using PostHog

  • Table of contents
      • Dashboards
      • Funnels
      • Group Analytics
      • Insights
      • Lifecycle
      • Path analysis
      • Retention
      • Stickiness
      • Trends
      • Heatmaps
      • Session Recording
      • Correlation Analysis
      • Experimentation
      • Feature Flags
      • Actions
      • Annotations
      • Cohorts
      • Data Management
      • Events
      • Persons
      • Sessions
      • UTM segmentation
      • Team collaboration
      • Organizations & projects
      • Settings
      • SSO & SAML
      • Toolbar
      • Notifications & alerts
  • Tutorials
    • All tutorials
    • Actions
    • Apps
    • Cohorts
    • Dashboards
    • Feature flags
    • Funnels
    • Heatmaps
    • Path analysis
    • Retention
    • Session recording
    • Trends
  • Support
  • Docs

  • Overview
    • Quickstart with PostHog Cloud
    • Overview
      • AWS
      • Azure
      • DigitalOcean
      • Google Cloud Platform
      • Hobby
      • Other platforms
      • Instance settings
      • Environment variables
      • Securing PostHog
      • Monitoring with Grafana
      • Running behind a proxy
      • Configuring email
      • Helm chart configuration
      • Deploying ClickHouse using Altinity.Cloud
      • Configuring Slack
      • Overview
        • Overview
        • Upgrade notes
        • Overview
        • 0001-events-sample-by
        • 0002_events_sample_by
        • 0003_fill_person_distinct_id2
        • ClickHouse
          • Backup
          • Kafka Engine
          • Resize disk
          • Restore
          • Vertical scaling
          • Horizontal scaling (Sharding & replication)
        • Kafka
          • Resize disk
          • Log retention
        • PostgreSQL
          • Resize disk
          • Troubleshooting long-running migrations
        • Plugin server
        • MinIO
        • Redis
        • Zookeeper
      • Disaster recovery
    • Troubleshooting and FAQs
    • Architecture
    • Managing hosting costs
    • EU-only hosting
    • Overview
    • Ingest live data
    • Ingest historical data
    • Identify users
    • User properties
    • Deploying a reverse proxy
    • Libraries
    • Badge
      • Snippet installation
      • Android
      • iOS
      • JavaScript
      • Flutter
      • React Native
      • Browser Extensions
      • Elixir
      • Go
      • Java
      • Node.js
      • PHP
      • Python
      • Ruby
      • Docusaurus v2
      • Gatsby
      • Google Tag Manager
      • Next.js
      • Nuxt.js
      • Retool
      • RudderStack
      • Segment
      • Sentry
      • Slack
      • Shopify
      • WordPress
      • Message formatting
      • Microsoft Teams
      • Slack
      • Discord
    • To another self-hosted instance
    • To PostHog from Amplitude
    • Between Cloud and self-hosted
    • Overview
    • Troubleshooting
      • Overview
      • Tutorial
      • TypeScript types
      • Developer reference
        • Amazon Kinesis Import
        • BitBucket Release Tracker
        • Braze Import
        • Event Replicator
        • GitHub Release Tracker
        • GitHub Star Sync
        • GitLab Release Tracker
        • Heartbeat
        • Ingestion Alert
        • Email Scoring
        • n8n Connector
        • Orbit Connector
        • Redshift Import
        • Segment Connector
        • Shopify Connector
        • Twitter Followers Tracker
        • Zendesk Connector
        • Airbyte Exporter
        • Amazon S3 Export
        • BigQuery Export
        • Customer.io Connector
        • Databricks Export
        • Engage Connector
        • GCP Pub/Sub Connector
        • Google Cloud Storage Export
        • Hubspot Connector
        • Intercom Connector
        • Migrator 3000
        • PagerDuty Connector
        • PostgreSQL Export
        • Redshift Export
        • RudderStack Export
        • Salesforce Connector
        • Sendgrid Connector
        • Sentry Connector
        • Snowflake Export
        • Twilio Connector
        • Variance Connector
        • Zapier Connector
        • Downsampler
        • Event Sequence Timer
        • First Time Event Tracker
        • Property Filter
        • Property Flattener
        • Schema Enforcer
        • Taxonomy Standardizer
        • Unduplicator
        • Automatic Cohort Creator
        • Currency Normalizer
        • GeoIP Enricher
        • Timestamp Parser
        • URL Normalizer
        • User Agent Populator
    • Overview
    • POST-only public endpoints
    • Actions
    • Annotations
    • Cohorts
    • Dashboards
    • Event definitions
    • Events
    • Experiments
    • Feature flags
    • Funnels
    • Groups
    • Groups types
    • Insights
    • Invites
    • Members
    • Persons
    • Plugin configs
    • Plugins
    • Projects
    • Property definitions
    • Session recordings
    • Trends
    • Users
    • Data model
    • Overview
    • GDPR guidance
    • HIPAA guidance
    • CCPA guidance
    • Data egress & compliance
    • Overview
    • Code of conduct
    • Recognizing contributions
  • Using PostHog

  • Table of contents
      • Dashboards
      • Funnels
      • Group Analytics
      • Insights
      • Lifecycle
      • Path analysis
      • Retention
      • Stickiness
      • Trends
      • Heatmaps
      • Session Recording
      • Correlation Analysis
      • Experimentation
      • Feature Flags
      • Actions
      • Annotations
      • Cohorts
      • Data Management
      • Events
      • Persons
      • Sessions
      • UTM segmentation
      • Team collaboration
      • Organizations & projects
      • Settings
      • SSO & SAML
      • Toolbar
      • Notifications & alerts
  • Tutorials
    • All tutorials
    • Actions
    • Apps
    • Cohorts
    • Dashboards
    • Feature flags
    • Funnels
    • Heatmaps
    • Path analysis
    • Retention
    • Session recording
    • Trends
  • Support
  • Docs
  • API
  • Insights

Insights

For instructions on how to authenticate to use this endpoint, see API overview.

Override the default in ModelViewSet that allows callers to destroy a model instance.

Endpoints

    GET/api/projects/:project_id/insights/
    POST/api/projects/:project_id/insights/
    GET/api/projects/:project_id/insights/:id/
    PATCH/api/projects/:project_id/insights/:id/
    DELETE/api/projects/:project_id/insights/:id/
    GET/api/projects/:project_id/insights/:id/activity/
    POST/api/projects/:project_id/insights/:id/viewed/
    GET/api/projects/:project_id/insights/activity/
    GET/api/projects/:project_id/insights/funnel/
    POST/api/projects/:project_id/insights/funnel/
    GET/api/projects/:project_id/insights/funnel/correlation/
    POST/api/projects/:project_id/insights/funnel/correlation/
    GET/api/projects/:project_id/insights/path/
    POST/api/projects/:project_id/insights/path/
    GET/api/projects/:project_id/insights/retention/
    GET/api/projects/:project_id/insights/trend/
    POST/api/projects/:project_id/insights/trend/

    List all insights

    Path Parameters

    • project_id
      string

    Query Parameters

    • created_by
      integer
    • format
      string
      One of: "csv""json"
    • limit
      integer
    • offset
      integer
    • short_id
      string

    Response


    Request

    GET /api/projects/:project_id/insights/

    Response

    {
    "count": 123,
    "next": "http://api.example.org/accounts/?offset=400&limit=100",
    "previous": "http://api.example.org/accounts/?offset=200&limit=100",
    "results": [
    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }
    ]
    }

    Create insights

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request Parameters


    • name
      string
    • derived_name
      string
    • filters
      object
    • order
      integer
    • deleted
      boolean
    • dashboards
      array

      A dashboard ID for each of the dashboards that this insight is displayed on.

    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Retrieve insights

    When loading an insight for a dashboard pass a from_dashboard query parameter containing the dashboard ID

    e.g. "/api/projects/{team_id}/insights/{insight_id}?from_dashboard={dashboard_id}"

    Insights can be added to more than one dashboard, this allows the insight to be loaded in the correct context.

    Using the correct cache and enriching the response with dashboard specific config (e.g. layouts or colors)

    Path Parameters

    • id
      integer
    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/:id/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Update insights

    Path Parameters

    • id
      integer
    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request Parameters


    • name
      string
    • derived_name
      string
    • filters
      object
    • order
      integer
    • deleted
      boolean
    • dashboards
      array

      A dashboard ID for each of the dashboards that this insight is displayed on.

    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    PATCH /api/projects/:project_id/insights/:id/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Delete insights

    Path Parameters

    • id
      integer
    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request

    DELETE /api/projects/:project_id/insights/:id/

    Response

    No response

    Retrieve insights activity retrieve

    Path Parameters

    • id
      integer
    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/:id/activity/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Create insights viewed

    Path Parameters

    • id
      integer
    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request Parameters


    • name
      string
    • derived_name
      string
    • filters
      object
    • order
      integer
    • deleted
      boolean
    • dashboards
      array

      A dashboard ID for each of the dashboards that this insight is displayed on.

    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/:id/viewed/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Retrieve insights activity

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/activity/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Retrieve insights funnel

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/funnel/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Create

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request Parameters


    • events
      Click to open
      array

      Events to filter on. One of events or actions is required.

    • actions
      Click to open
      array

      Actions to filter on. One of events or actions is required.

    • properties

      Filter events by event property, person property, cohort, groups and more.

    • filter_test_accounts
      boolean

      Whether to filter out internal and test accounts. See "project settings" in your PostHog account for the filters.

    • date_from
      string
      Default: -7d

      What date to filter the results from. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

    • date_to
      string
      Default: -7d

      What date to filter the results to. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

    • breakdown
      string

      A property or cohort to break down on. You can select the type of the property with breakdown_type.

      • event (default): a property key
      • person: a person property key
      • cohort: an array of cohort IDs (ie [9581,5812])
    • breakdown_type
      string
      Default: event
      One of: "event""person""cohort""group""session"

      Type of property to break down on.

    • funnel_window_interval
      integer
      Default: 14

      Funnel window size. Set in combination with funnel_window_interval, so defaults to 'days'.

    • funnel_window_interval_type
      string
      Default: days
      One of: "DAY""MINUTE""HOUR""WEEK""MONTH"

      The type of interval. Used in combination with funnel_window_intervals.

    • funnel_viz_type
      string
      Default: steps
      One of: "trends""time_to_convert""steps"

      The visualisation type.

      • steps Track instances progress between steps of the funnel
      • trends Track how this funnel's conversion rate is trending over time.
      • time_to_convert Track how long it takes for instances to convert
    • funnel_order_type
      string
      Default: ordered
      One of: "strict""unordered""ordered"
      • ordered - Step B must happen after Step A, but any number events can happen between A and B.
      • strict - Step B must happen directly after Step A without any events in between.
      • unordered - Steps can be completed in any sequence.
    • exclusions
      Click to open
      array

      Exclude users/groups that completed the specified event between two specific steps. Note that these users/groups will be completely excluded from the entire funnel.

    • aggregation_group_type_index
      integer
      0

      Aggregate by users or by groups. 0 means user, >0 means a group. See interface for the corresponding ID of the group.

    • breakdown_limit
      integer
      Default: 10
    • funnel_window_days
      integer
      Default: 14

      (DEPRECATED) Funnel window size in days. Use funnel_window_interval and funnel_window_interval_type

    Response


    Request

    POST /api/projects/:project_id/insights/funnel/

    Response

    {
    "is_cached": true,
    "last_refresh": "2019-08-24T14:15:22Z",
    "timezone": "Africa/Abidjan",
    "result": [
    {
    "count": 0,
    "action_id": "string",
    "average_conversion_time": 0,
    "median_conversion_time": 0,
    "converted_people_url": "string",
    "dropped_people_url": "string",
    "order": "string"
    }
    ]
    }

    Retrieve insights funnel correlation

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/funnel/correlation/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Create insights funnel correlation

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request Parameters


    • name
      string
    • derived_name
      string
    • filters
      object
    • order
      integer
    • deleted
      boolean
    • dashboards
      array

      A dashboard ID for each of the dashboards that this insight is displayed on.

    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/funnel/correlation/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Retrieve insights path

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/path/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Create insights path

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request Parameters


    • name
      string
    • derived_name
      string
    • filters
      object
    • order
      integer
    • deleted
      boolean
    • dashboards
      array

      A dashboard ID for each of the dashboards that this insight is displayed on.

    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/path/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Retrieve insights retention

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/retention/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Retrieve insights trend

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Response


    Request

    GET /api/projects/:project_id/insights/trend/

    Response

    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": {
    "property1": null,
    "property2": null
    },
    "filters_hash": "string",
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "last_refresh": "string",
    "refreshing": true,
    "result": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "description": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "tags": [
    null
    ],
    "favorited": true,
    "saved": true,
    "last_modified_at": "2019-08-24T14:15:22Z",
    "last_modified_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "email": "user@example.com"
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string"
    }

    Create

    Path Parameters

    • project_id
      string

    Query Parameters

    • format
      string
      One of: "csv""json"

    Request Parameters


    • events
      Click to open
      array

      Events to filter on. One of events or actions is required.

    • actions
      Click to open
      array

      Actions to filter on. One of events or actions is required.

    • properties

      Filter events by event property, person property, cohort, groups and more.

    • filter_test_accounts
      boolean

      Whether to filter out internal and test accounts. See "project settings" in your PostHog account for the filters.

    • date_from
      string
      Default: -7d

      What date to filter the results from. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

    • date_to
      string
      Default: -7d

      What date to filter the results to. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

    • breakdown
      string

      A property or cohort to break down on. You can select the type of the property with breakdown_type.

      • event (default): a property key
      • person: a person property key
      • cohort: an array of cohort IDs (ie [9581,5812])
    • breakdown_type
      string
      Default: event
      One of: "event""person""cohort""group""session"

      Type of property to break down on.

    • display
      string
      Default: ActionsLineGraph
      One of: "ActionsLineGraph""ActionsLineGraphCumulative""ActionsTable""ActionsPie""ActionsBar""ActionsBarValue""WorldMap""BoldNumber"

      How to display the data. Will change how the data is returned.

    • formula
      string

      Combine the result of events or actions into a single number. For example A + B or (A-B)/B. The letters correspond to the order of the events or actions lists.

    • compare
      boolean

      For each returned result show the current period and the previous period. The result will contain compare:true and a compare_label with either current or previous.

    Response


    Request

    POST /api/projects/:project_id/insights/trend/

    Response

    {
    "is_cached": true,
    "last_refresh": "2019-08-24T14:15:22Z",
    "timezone": "Africa/Abidjan",
    "result": [
    {
    "data": [
    0
    ],
    "days": [
    "2019-08-24"
    ],
    "labels": [
    "string"
    ],
    "filter": {
    "events": [
    {
    "id": "string",
    "properties": [
    {
    "type": "AND",
    "values": [
    {
    "key": "string",
    "value": "string",
    "operator": "exact",
    "type": "event"
    }
    ]
    }
    ],
    "math": "total"
    }
    ],
    "actions": [
    {
    "id": "string",
    "properties": [
    {
    "type": "AND",
    "values": [
    {
    "key": "string",
    "value": "string",
    "operator": "exact",
    "type": "event"
    }
    ]
    }
    ],
    "math": "total"
    }
    ],
    "properties": {
    "type": "AND",
    "values": [
    {
    "key": "string",
    "value": "string",
    "operator": "exact",
    "type": "event"
    }
    ]
    },
    "filter_test_accounts": false,
    "date_from": "-7d",
    "date_to": "-7d"
    },
    "label": "string"
    }
    ]
    }

    Questions?

    Was this page useful?

    • About
    • Blog
    • Newsletter
    • Careers
    • Support
    • Contact sales

    Product OS suite

    Product overview

    Analytics
    • Funnels
    • Trends
    • Paths

    Pricing

    Features
    • Session recording
    • Feature flags
    • Experimentation
    • Heatmaps

    Customers

    Platform
    • Correlation analysis
    • Collaboration
    • Apps

    Community

    Discussion
    • Questions?
    • Slack
    • Issues
    • Contact sales
    Get involved
    • Roadmap
    • Contributors
    • Merch
    • PostHog FM
    • Marketplace

    Docs

    Getting started
    • PostHog Cloud
    • Self-hosted
    • Compare options
    • Tutorials
    • PostHog on GitHub
    Install & integrate
    • Installation
    • Docs
    • API
    • Apps
    User guides
    • Cohorts
    • Funnels
    • Sessions
    • Data
    • Events

    Company

    About
    • Our story
    • Team
    • Handbook
    • Investors
    • Careers
    Resources
    • FAQ
    • Ask a question
    • Blog
    • Press
    • Merch
    • YouTube
    © 2022 PostHog, Inc.
    • Code of conduct
    • Privacy
    • Terms