Surveys
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
List all surveys
Required API key scopes
survey:read
Path parameters
- project_idstring
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
- limitinteger
Number of results to return per page.
- offsetinteger
The initial index from which to return the results.
Response
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/
Response
Status 200
{"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","linked_flag": {"id": 0,"team_id": 0,"name": "string","key": "string","filters": {"property1": null,"property2": null},"deleted": true,"active": true,"ensure_experience_continuity": true},"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},"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},"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}},"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": 2147483647,"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}]}
Create surveys
Required API key scopes
survey:write
Path parameters
- project_idstring
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
- namestring
- descriptionstring
- type
- linked_flag_idinteger
- targeting_flag_idinteger
- targeting_flag_filters
- remove_targeting_flagboolean
- 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) - `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) - `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) - `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 - `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_datestring
- end_datestring
- archivedboolean
- responses_limitinteger
- iteration_countinteger
- iteration_frequency_daysinteger
- iteration_start_datesarray
- current_iterationinteger
- current_iteration_start_datestring
- response_sampling_start_datestring
- response_sampling_interval_type
- response_sampling_intervalinteger
- response_sampling_limitinteger
- response_sampling_daily_limits
Response
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
Response
Status 201
{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08","name": "string","description": "string","type": "popover","linked_flag": {"id": 0,"team_id": 0,"name": "string","key": "string","filters": {"property1": null,"property2": null},"deleted": true,"active": true,"ensure_experience_continuity": true},"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},"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},"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}},"start_date": "2019-08-24T14:15:22Z","end_date": "2019-08-24T14:15:22Z","archived": true,"responses_limit": 2147483647,"iteration_count": 2147483647,"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}
Retrieve surveys
Required API key scopes
survey:read
Path parameters
- idstring
A UUID string identifying this survey.
- project_idstring
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
Response
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/
Response
Status 200
{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08","name": "string","description": "string","type": "popover","linked_flag": {"id": 0,"team_id": 0,"name": "string","key": "string","filters": {"property1": null,"property2": null},"deleted": true,"active": true,"ensure_experience_continuity": true},"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},"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},"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}},"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": 2147483647,"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}
Update surveys
Required API key scopes
survey:write
Path parameters
- idstring
A UUID string identifying this survey.
- project_idstring
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
- namestring
- descriptionstring
- type
- linked_flag_idinteger
- targeting_flag_idinteger
- targeting_flag_filters
- remove_targeting_flagboolean
- 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) - `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) - `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) - `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 - `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_datestring
- end_datestring
- archivedboolean
- responses_limitinteger
- iteration_countinteger
- iteration_frequency_daysinteger
- iteration_start_datesarray
- current_iterationinteger
- current_iteration_start_datestring
- response_sampling_start_datestring
- response_sampling_interval_type
- response_sampling_intervalinteger
- response_sampling_limitinteger
- response_sampling_daily_limits
Response
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"
Response
Status 200
{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08","name": "string","description": "string","type": "popover","linked_flag": {"id": 0,"team_id": 0,"name": "string","key": "string","filters": {"property1": null,"property2": null},"deleted": true,"active": true,"ensure_experience_continuity": true},"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},"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},"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}},"start_date": "2019-08-24T14:15:22Z","end_date": "2019-08-24T14:15:22Z","archived": true,"responses_limit": 2147483647,"iteration_count": 2147483647,"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}
Delete surveys
Required API key scopes
survey:write
Path parameters
- idstring
A UUID string identifying this survey.
- project_idstring
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
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/
Response
Status 204 No response body
Retrieve surveys activity retrieve
Required API key scopes
activity_log:read
Path parameters
- idstring
A UUID string identifying this survey.
- project_idstring
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
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/
Response
Status 200 No response body
Create surveys summarize responses
Required API key scopes
survey:read
Path parameters
- idstring
A UUID string identifying this survey.
- project_idstring
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
- namestring
- descriptionstring
- type
- linked_flag_idinteger
- targeting_flag_idinteger
- targeting_flag_filters
- remove_targeting_flagboolean
- 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) - `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) - `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) - `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 - `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_datestring
- end_datestring
- archivedboolean
- responses_limitinteger
- iteration_countinteger
- iteration_frequency_daysinteger
- iteration_start_datesarray
- current_iterationinteger
- current_iteration_start_datestring
- response_sampling_start_datestring
- response_sampling_interval_type
- response_sampling_intervalinteger
- response_sampling_limitinteger
- response_sampling_daily_limits
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
Response
Status 200 No response body
Retrieve surveys activity
Required API key scopes
activity_log:read
Path parameters
- project_idstring
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
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/
Response
Status 200 No response body
Retrieve surveys responses count
Required API key scopes
survey:read
Path parameters
- project_idstring
Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.
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/