Survey

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

Endpoints

GET
POST
GET
PATCH
DELETE
GET
GET
POST
GET
GET
GET

List all surveys

Required API key scopes

survey:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

  • limit
    integer

    Number of results to return per page.

  • offset
    integer

    The initial index from which to return the results.

  • search
    string

    A search term.

Response


Example request

GET /api/projects/:project_id/surveys
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/

Example response

Status 200
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": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "type": "popover",
      "schedule": "string",
      "linked_flag": {
        "id": 0,
        "team_id": 0,
        "name": "string",
        "key": "string",
        "filters": {
          "property1": null,
          "property2": null
        },
        "deleted": true,
        "active": true,
        "ensure_experience_continuity": true,
        "has_encrypted_payloads": true,
        "version": -2147483648,
        "evaluation_runtime": "server",
        "evaluation_tags": [
          "string"
        ]
      },
      "linked_flag_id": 0,
      "targeting_flag": {
        "id": 0,
        "team_id": 0,
        "name": "string",
        "key": "string",
        "filters": {
          "property1": null,
          "property2": null
        },
        "deleted": true,
        "active": true,
        "ensure_experience_continuity": true,
        "has_encrypted_payloads": true,
        "version": -2147483648,
        "evaluation_runtime": "server",
        "evaluation_tags": [
          "string"
        ]
      },
      "internal_targeting_flag": {
        "id": 0,
        "team_id": 0,
        "name": "string",
        "key": "string",
        "filters": {
          "property1": null,
          "property2": null
        },
        "deleted": true,
        "active": true,
        "ensure_experience_continuity": true,
        "has_encrypted_payloads": true,
        "version": -2147483648,
        "evaluation_runtime": "server",
        "evaluation_tags": [
          "string"
        ]
      },
      "questions": null,
      "conditions": "string",
      "appearance": null,
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {
          "property1": null,
          "property2": null
        },
        "role_at_organization": "engineering"
      },
      "start_date": "2019-08-24T14:15:22Z",
      "end_date": "2019-08-24T14:15:22Z",
      "archived": true,
      "responses_limit": 2147483647,
      "feature_flag_keys": [
        null
      ],
      "iteration_count": 500,
      "iteration_frequency_days": 2147483647,
      "iteration_start_dates": [
        "2019-08-24T14:15:22Z"
      ],
      "current_iteration": 2147483647,
      "current_iteration_start_date": "2019-08-24T14:15:22Z",
      "response_sampling_start_date": "2019-08-24T14:15:22Z",
      "response_sampling_interval_type": "day",
      "response_sampling_interval": 2147483647,
      "response_sampling_limit": 2147483647,
      "response_sampling_daily_limits": null,
      "enable_partial_responses": true
    }
  ]
}

Create surveys

Required API key scopes

survey:write

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
    string
  • linked_flag_id
    integer
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    boolean
  • questions
        The `array` of questions included in the survey. Each question must conform to one of the defined question types: Basic, Link, Rating, or Multiple Choice.

    Basic (open-ended question)
    - `id`: The question ID
    - `type`: `open`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `branching`: Branching logic for the question. See branching types below for details.

    Link (a question with a link)
    - `id`: The question ID
    - `type`: `link`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `link`: The URL associated with the question.
    - `branching`: Branching logic for the question. See branching types below for details.

    Rating (a question with a rating scale)
    - `id`: The question ID
    - `type`: `rating`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `display`: Display style of the rating (`number` or `emoji`).
    - `scale`: The scale of the rating (`number`).
    - `lowerBoundLabel`: Label for the lower bound of the scale.
    - `upperBoundLabel`: Label for the upper bound of the scale.
    - `branching`: Branching logic for the question. See branching types below for details.

    Multiple choice
    - `id`: The question ID
    - `type`: `single_choice` or `multiple_choice`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `choices`: An array of choices for the question.
    - `shuffleOptions`: Whether to shuffle the order of the choices (`boolean`).
    - `hasOpenChoice`: Whether the question allows an open-ended response (`boolean`).
    - `branching`: Branching logic for the question. See branching types below for details.

    Branching logic can be one of the following types:

    Next question: Proceeds to the next question
    ```json
    {
        "type": "next_question"
    }
    ```

    End: Ends the survey, optionally displaying a confirmation message.
    ```json
    {
        "type": "end"
    }
    ```

    Response-based: Branches based on the response values. Available for the `rating` and `single_choice` question types.
    ```json
    {
        "type": "response_based",
        "responseValues": {
            "responseKey": "value"
        }
    }
    ```

    Specific question: Proceeds to a specific question by index.
    ```json
    {
        "type": "specific_question",
        "index": 2
    }
    ```
  • conditions
  • appearance
  • start_date
    string
  • end_date
    string
  • archived
    boolean
  • responses_limit
    integer
  • iteration_count
    integer
  • iteration_frequency_days
    integer
  • iteration_start_dates
    array
  • current_iteration
    integer
  • current_iteration_start_date
    string
  • response_sampling_start_date
    string
  • response_sampling_interval_type
  • response_sampling_interval
    integer
  • response_sampling_limit
    integer
  • response_sampling_daily_limits
  • enable_partial_responses
    boolean
  • _create_in_folder
    string

Response


Example request

POST /api/projects/:project_id/surveys
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/\
	-d name="string",\
	-d type=undefined

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "type": "popover",
  "schedule": "string",
  "linked_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "linked_flag_id": 0,
  "targeting_flag_id": 0,
  "targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "targeting_flag_filters": null,
  "remove_targeting_flag": true,
  "questions": null,
  "conditions": null,
  "appearance": null,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "archived": true,
  "responses_limit": 2147483647,
  "iteration_count": 500,
  "iteration_frequency_days": 2147483647,
  "iteration_start_dates": [
    "2019-08-24T14:15:22Z"
  ],
  "current_iteration": 2147483647,
  "current_iteration_start_date": "2019-08-24T14:15:22Z",
  "response_sampling_start_date": "2019-08-24T14:15:22Z",
  "response_sampling_interval_type": "day",
  "response_sampling_interval": 2147483647,
  "response_sampling_limit": 2147483647,
  "response_sampling_daily_limits": null,
  "enable_partial_responses": true,
  "_create_in_folder": "string"
}

Retrieve surveys

Required API key scopes

survey:read

Path parameters

  • id
    string

    A UUID string identifying this survey.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Response


Example request

GET /api/projects/:project_id/surveys/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "type": "popover",
  "schedule": "string",
  "linked_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "linked_flag_id": 0,
  "targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "questions": null,
  "conditions": "string",
  "appearance": null,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "archived": true,
  "responses_limit": 2147483647,
  "feature_flag_keys": [
    null
  ],
  "iteration_count": 500,
  "iteration_frequency_days": 2147483647,
  "iteration_start_dates": [
    "2019-08-24T14:15:22Z"
  ],
  "current_iteration": 2147483647,
  "current_iteration_start_date": "2019-08-24T14:15:22Z",
  "response_sampling_start_date": "2019-08-24T14:15:22Z",
  "response_sampling_interval_type": "day",
  "response_sampling_interval": 2147483647,
  "response_sampling_limit": 2147483647,
  "response_sampling_daily_limits": null,
  "enable_partial_responses": true
}

Update surveys

Required API key scopes

survey:write

Path parameters

  • id
    string

    A UUID string identifying this survey.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
    string
  • linked_flag_id
    integer
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    boolean
  • questions
        The `array` of questions included in the survey. Each question must conform to one of the defined question types: Basic, Link, Rating, or Multiple Choice.

    Basic (open-ended question)
    - `id`: The question ID
    - `type`: `open`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `branching`: Branching logic for the question. See branching types below for details.

    Link (a question with a link)
    - `id`: The question ID
    - `type`: `link`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `link`: The URL associated with the question.
    - `branching`: Branching logic for the question. See branching types below for details.

    Rating (a question with a rating scale)
    - `id`: The question ID
    - `type`: `rating`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `display`: Display style of the rating (`number` or `emoji`).
    - `scale`: The scale of the rating (`number`).
    - `lowerBoundLabel`: Label for the lower bound of the scale.
    - `upperBoundLabel`: Label for the upper bound of the scale.
    - `branching`: Branching logic for the question. See branching types below for details.

    Multiple choice
    - `id`: The question ID
    - `type`: `single_choice` or `multiple_choice`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `choices`: An array of choices for the question.
    - `shuffleOptions`: Whether to shuffle the order of the choices (`boolean`).
    - `hasOpenChoice`: Whether the question allows an open-ended response (`boolean`).
    - `branching`: Branching logic for the question. See branching types below for details.

    Branching logic can be one of the following types:

    Next question: Proceeds to the next question
    ```json
    {
        "type": "next_question"
    }
    ```

    End: Ends the survey, optionally displaying a confirmation message.
    ```json
    {
        "type": "end"
    }
    ```

    Response-based: Branches based on the response values. Available for the `rating` and `single_choice` question types.
    ```json
    {
        "type": "response_based",
        "responseValues": {
            "responseKey": "value"
        }
    }
    ```

    Specific question: Proceeds to a specific question by index.
    ```json
    {
        "type": "specific_question",
        "index": 2
    }
    ```
  • conditions
  • appearance
  • start_date
    string
  • end_date
    string
  • archived
    boolean
  • responses_limit
    integer
  • iteration_count
    integer
  • iteration_frequency_days
    integer
  • iteration_start_dates
    array
  • current_iteration
    integer
  • current_iteration_start_date
    string
  • response_sampling_start_date
    string
  • response_sampling_interval_type
  • response_sampling_interval
    integer
  • response_sampling_limit
    integer
  • response_sampling_daily_limits
  • enable_partial_responses
    boolean
  • _create_in_folder
    string

Response


Example request

PATCH /api/projects/:project_id/surveys/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/:id/\
	-d name="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "type": "popover",
  "schedule": "string",
  "linked_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "linked_flag_id": 0,
  "targeting_flag_id": 0,
  "targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {
      "property1": null,
      "property2": null
    },
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "has_encrypted_payloads": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "evaluation_tags": [
      "string"
    ]
  },
  "targeting_flag_filters": null,
  "remove_targeting_flag": true,
  "questions": null,
  "conditions": null,
  "appearance": null,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
      "property1": null,
      "property2": null
    },
    "role_at_organization": "engineering"
  },
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "archived": true,
  "responses_limit": 2147483647,
  "iteration_count": 500,
  "iteration_frequency_days": 2147483647,
  "iteration_start_dates": [
    "2019-08-24T14:15:22Z"
  ],
  "current_iteration": 2147483647,
  "current_iteration_start_date": "2019-08-24T14:15:22Z",
  "response_sampling_start_date": "2019-08-24T14:15:22Z",
  "response_sampling_interval_type": "day",
  "response_sampling_interval": 2147483647,
  "response_sampling_limit": 2147483647,
  "response_sampling_daily_limits": null,
  "enable_partial_responses": true,
  "_create_in_folder": "string"
}

Delete surveys

Required API key scopes

survey:write

Path parameters

  • id
    string

    A UUID string identifying this survey.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

DELETE /api/projects/:project_id/surveys/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/:id/

Example response

Status 204 No response body

Retrieve surveys activity retrieve

Required API key scopes

activity_log:read

Path parameters

  • id
    string

    A UUID string identifying this survey.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

GET /api/projects/:project_id/surveys/:id/activity
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/:id/activity/

Example response

Status 200 No response body

Retrieve surveys stats retrieve

Get survey response statistics for a specific survey.

Args: date_from: Optional ISO timestamp for start date (e.g. 2024-01-01T00:00:00Z) date_to: Optional ISO timestamp for end date (e.g. 2024-01-31T23:59:59Z)

Returns: Survey statistics including event counts, unique respondents, and conversion rates

Required API key scopes

survey:read

Path parameters

  • id
    string

    A UUID string identifying this survey.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

GET /api/projects/:project_id/surveys/:id/stats
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/:id/stats/

Example response

Status 200 No response body

Create surveys summarize responses

Required API key scopes

survey:read

Path parameters

  • id
    string

    A UUID string identifying this survey.

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
    string
  • linked_flag_id
    integer
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    boolean
  • questions
        The `array` of questions included in the survey. Each question must conform to one of the defined question types: Basic, Link, Rating, or Multiple Choice.

    Basic (open-ended question)
    - `id`: The question ID
    - `type`: `open`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `branching`: Branching logic for the question. See branching types below for details.

    Link (a question with a link)
    - `id`: The question ID
    - `type`: `link`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `link`: The URL associated with the question.
    - `branching`: Branching logic for the question. See branching types below for details.

    Rating (a question with a rating scale)
    - `id`: The question ID
    - `type`: `rating`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `display`: Display style of the rating (`number` or `emoji`).
    - `scale`: The scale of the rating (`number`).
    - `lowerBoundLabel`: Label for the lower bound of the scale.
    - `upperBoundLabel`: Label for the upper bound of the scale.
    - `branching`: Branching logic for the question. See branching types below for details.

    Multiple choice
    - `id`: The question ID
    - `type`: `single_choice` or `multiple_choice`
    - `question`: The text of the question.
    - `description`: Optional description of the question.
    - `descriptionContentType`: Content type of the description (`html` or `text`).
    - `optional`: Whether the question is optional (`boolean`).
    - `buttonText`: Text displayed on the submit button.
    - `choices`: An array of choices for the question.
    - `shuffleOptions`: Whether to shuffle the order of the choices (`boolean`).
    - `hasOpenChoice`: Whether the question allows an open-ended response (`boolean`).
    - `branching`: Branching logic for the question. See branching types below for details.

    Branching logic can be one of the following types:

    Next question: Proceeds to the next question
    ```json
    {
        "type": "next_question"
    }
    ```

    End: Ends the survey, optionally displaying a confirmation message.
    ```json
    {
        "type": "end"
    }
    ```

    Response-based: Branches based on the response values. Available for the `rating` and `single_choice` question types.
    ```json
    {
        "type": "response_based",
        "responseValues": {
            "responseKey": "value"
        }
    }
    ```

    Specific question: Proceeds to a specific question by index.
    ```json
    {
        "type": "specific_question",
        "index": 2
    }
    ```
  • conditions
  • appearance
  • start_date
    string
  • end_date
    string
  • archived
    boolean
  • responses_limit
    integer
  • iteration_count
    integer
  • iteration_frequency_days
    integer
  • iteration_start_dates
    array
  • current_iteration
    integer
  • current_iteration_start_date
    string
  • response_sampling_start_date
    string
  • response_sampling_interval_type
  • response_sampling_interval
    integer
  • response_sampling_limit
    integer
  • response_sampling_daily_limits
  • enable_partial_responses
    boolean
  • _create_in_folder
    string

Example request

POST /api/projects/:project_id/surveys/:id/summarize_responses
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/:id/summarize_responses/\
	-d name="string",\
	-d type=undefined

Example response

Status 200 No response body

Retrieve surveys activity

Required API key scopes

activity_log:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

GET /api/projects/:project_id/surveys/activity
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/activity/

Example response

Status 200 No response body

Retrieve surveys responses count

Required API key scopes

survey:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

GET /api/projects/:project_id/surveys/responses_count
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/responses_count/

Example response

Status 200 No response body

Retrieve surveys stats

Get aggregated response statistics across all surveys.

Args: date_from: Optional ISO timestamp for start date (e.g. 2024-01-01T00:00:00Z) date_to: Optional ISO timestamp for end date (e.g. 2024-01-31T23:59:59Z)

Returns: Aggregated statistics across all surveys including total counts and rates

Required API key scopes

survey:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Example request

GET /api/projects/:project_id/surveys/stats
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/surveys/stats/

Example response

Status 200 No response body

Community questions

Questions about this page? or post a community question.