Survey API Reference

Survey

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`GET`
`GET`
`POST`
`POST`
`POST`
`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,
      "linked_insight_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,
      "user_access_level": "string"
    }
  ]
}

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
linked_insight_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.
    - `isNpsQuestion`: Whether the question is an NPS rating.
    - `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,
  "linked_insight_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,
  "linked_insight_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,
  "user_access_level": "string"
}

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
linked_insight_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.
    - `isNpsQuestion`: Whether the question is an NPS rating.
    - `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,
  "linked_insight_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 archived response uuids

Get list of archived response UUIDs for HogQL filtering.

Returns list of UUIDs that the frontend can use to filter out archived responses in HogQL queries.

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/archived-response-uuids

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/archived-response-uuids/

Example response

Status 200 No response body

Create surveys duplicate to projects

Duplicate a survey to multiple projects in a single transaction.

Accepts a list of target team IDs and creates a copy of the survey in each project. Uses an all-or-nothing approach - if any duplication fails, all changes are rolled back.

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
linked_insight_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.
    - `isNpsQuestion`: Whether the question is an NPS rating.
    - `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/duplicate_to_projects

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/duplicate_to_projects/\
	-d name="string",\
	-d type=undefined

Example response

Status 200 No response body

Create surveys responses archive

Archive a single survey response.

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/.
response_uuid
string

Request parameters

name
string
description
string
type
schedule
string
linked_flag_id
integer
linked_insight_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.
    - `isNpsQuestion`: Whether the question is an NPS rating.
    - `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/responses/:response_uuid/archive

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/responses/:response_uuid/archive/\
	-d name="string",\
	-d type=undefined

Example response

Status 200 No response body

Create surveys responses unarchive

Unarchive a single survey response.

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/.
response_uuid
string

Request parameters

name
string
description
string
type
schedule
string
linked_flag_id
integer
linked_insight_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.
    - `isNpsQuestion`: Whether the question is an NPS rating.
    - `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/responses/:response_uuid/unarchive

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/responses/:response_uuid/unarchive/\
	-d name="string",\
	-d type=undefined

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) exclude_archived: Optional boolean to exclude archived responses (default: false, includes archived)

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
linked_insight_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.
    - `isNpsQuestion`: Whether the question is an NPS rating.
    - `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

Get response counts for all surveys.

Args: exclude_archived: Optional boolean to exclude archived responses (default: false, includes archived) survey_ids: Optional comma-separated list of survey IDs to filter by

Returns: Dictionary mapping survey IDs to response counts

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/