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
POST
GET
POST
POST
POST
GET
GET
Next page →

List all surveys

Also available via the PostHog MCP server:

  • surveys-get-all — List surveys in the project (server-side search + filters).

Required API key scopes

survey:read

Query parameters

  • archived
    boolean
  • ids
    array
  • limit
    integer
  • offset
    integer
  • search
    string
  • type
    string
    One of: "api""external_survey""popover""widget"

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": {},
        "deleted": true,
        "active": true,
        "ensure_experience_continuity": true,
        "version": -2147483648,
        "evaluation_runtime": "server",
        "bucketing_identifier": "distinct_id",
        "evaluation_contexts": [
          "string"
        ]
      },
      "linked_flag_id": 0,
      "linked_insight_id": 0,
      "targeting_flag": {
        "id": 0,
        "team_id": 0,
        "name": "string",
        "key": "string",
        "filters": {},
        "deleted": true,
        "active": true,
        "ensure_experience_continuity": true,
        "version": -2147483648,
        "evaluation_runtime": "server",
        "bucketing_identifier": "distinct_id",
        "evaluation_contexts": [
          "string"
        ]
      },
      "internal_targeting_flag": {
        "id": 0,
        "team_id": 0,
        "name": "string",
        "key": "string",
        "filters": {},
        "deleted": true,
        "active": true,
        "ensure_experience_continuity": true,
        "version": -2147483648,
        "evaluation_runtime": "server",
        "bucketing_identifier": "distinct_id",
        "evaluation_contexts": [
          "string"
        ]
      },
      "questions": null,
      "conditions": {},
      "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": {},
        "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": [
        {
          "property1": "string",
          "property2": "string"
        }
      ],
      "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,
      "enable_iframe_embedding": true,
      "base_language": "string",
      "translations": null,
      "user_access_level": "string",
      "form_content": null,
      "search_match_type": "exact"
    }
  ]
}

Create surveys

Required API key scopes

survey:write

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
  • linked_flag_id
    integernull
  • linked_insight_id
    integernull
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    booleannull
  • questions
    Click to open
    arraynull
  • conditions
  • appearance
  • start_date
    stringnull
  • end_date
    stringnull
  • archived
    boolean
  • responses_limit
    integernull
  • iteration_count
    integernull
  • iteration_frequency_days
    integernull
  • iteration_start_dates
    arraynull
  • current_iteration
    integernull
  • current_iteration_start_date
    stringnull
  • response_sampling_start_date
    stringnull
  • response_sampling_interval_type
  • response_sampling_interval
    integernull
  • response_sampling_limit
    integernull
  • response_sampling_daily_limits
  • enable_partial_responses
    booleannull
  • enable_iframe_embedding
    booleannull
  • base_language
    string
  • translations
  • _create_in_folder
    string
  • form_content

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": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "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": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "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": {},
    "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,
  "enable_iframe_embedding": true,
  "base_language": "string",
  "translations": null,
  "_create_in_folder": "string",
  "form_content": null
}

Retrieve surveys

Required API key scopes

survey:read

Path parameters

  • id
    string

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": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "linked_flag_id": 0,
  "linked_insight_id": 0,
  "targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "questions": null,
  "conditions": {},
  "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": {},
    "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": [
    {
      "property1": "string",
      "property2": "string"
    }
  ],
  "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,
  "enable_iframe_embedding": true,
  "base_language": "string",
  "translations": null,
  "user_access_level": "string",
  "form_content": null,
  "search_match_type": "exact"
}

Update surveys

Required API key scopes

survey:write

Path parameters

  • id
    string

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
  • linked_flag_id
    integernull
  • linked_insight_id
    integernull
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    booleannull
  • questions
    Click to open
    arraynull
  • conditions
  • appearance
  • start_date
    stringnull
  • end_date
    stringnull
  • archived
    boolean
  • responses_limit
    integernull
  • iteration_count
    integernull
  • iteration_frequency_days
    integernull
  • iteration_start_dates
    arraynull
  • current_iteration
    integernull
  • current_iteration_start_date
    stringnull
  • response_sampling_start_date
    stringnull
  • response_sampling_interval_type
  • response_sampling_interval
    integernull
  • response_sampling_limit
    integernull
  • response_sampling_daily_limits
  • enable_partial_responses
    booleannull
  • enable_iframe_embedding
    booleannull
  • base_language
    string
  • translations
  • _create_in_folder
    string
  • form_content

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": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "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": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "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": {},
    "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,
  "enable_iframe_embedding": true,
  "base_language": "string",
  "translations": null,
  "_create_in_folder": "string",
  "form_content": null
}

Delete surveys

Required API key scopes

survey:write

Path parameters

  • id
    string

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

Required API key scopes

activity_log:read

Path parameters

  • id
    string

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

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

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
    stringnull
  • linked_flag_id
    integernull
  • linked_insight_id
    integernull
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    booleannull
  • questions
  • conditions
  • appearance
  • start_date
    stringnull
  • end_date
    stringnull
  • archived
    boolean
  • responses_limit
    integernull
  • iteration_count
    integernull
  • iteration_frequency_days
    integernull
  • iteration_start_dates
    arraynull
  • current_iteration
    integernull
  • current_iteration_start_date
    stringnull
  • response_sampling_start_date
    stringnull
  • response_sampling_interval_type
  • response_sampling_interval
    integernull
  • response_sampling_limit
    integernull
  • response_sampling_daily_limits
  • enable_partial_responses
    booleannull
  • enable_iframe_embedding
    booleannull
  • base_language
    string
  • translations
  • _create_in_folder
    string
  • form_content

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 generate translations

Required API key scopes

survey:write

Path parameters

  • id
    string

Request parameters

  • target_language
    string
  • source_language
    string
  • overwrite
    boolean
    Default: false
  • survey
    object

Response


Example request

POST /api/projects/:project_id/surveys/:id/generate_translations
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/generate_translations/\
	-d target_language="string"

Example response

Status 200
RESPONSE
{
  "translations": {
    "property1": {
      "name": "string",
      "thankYouMessageHeader": "string",
      "thankYouMessageDescription": "string",
      "thankYouMessageCloseButtonText": "string"
    },
    "property2": {
      "name": "string",
      "thankYouMessageHeader": "string",
      "thankYouMessageDescription": "string",
      "thankYouMessageCloseButtonText": "string"
    }
  },
  "questions": [
    {
      "id": "string",
      "translations": {
        "property1": {
          "question": "string",
          "description": "string",
          "buttonText": "string",
          "choices": [
            "string"
          ],
          "lowerBoundLabel": "string",
          "upperBoundLabel": "string",
          "link": "string"
        },
        "property2": {
          "question": "string",
          "description": "string",
          "buttonText": "string",
          "choices": [
            "string"
          ],
          "lowerBoundLabel": "string",
          "upperBoundLabel": "string",
          "link": "string"
        }
      }
    }
  ],
  "generated_field_paths": [
    "string"
  ],
  "trace_id": "string"
}

Create surveys

Launch a survey by setting start_date to the current time. No-op if the survey is already launched (start_date set in the past) — returns the existing state unchanged. Does not affect archived surveys or surveys with an end_date in the past; unarchive or extend the end_date first.

Required API key scopes

survey:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/surveys/:id/launch
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/launch/

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": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "linked_flag_id": 0,
  "linked_insight_id": 0,
  "targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "questions": null,
  "conditions": {},
  "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": {},
    "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": [
    {
      "property1": "string",
      "property2": "string"
    }
  ],
  "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,
  "enable_iframe_embedding": true,
  "base_language": "string",
  "translations": null,
  "user_access_level": "string",
  "form_content": null,
  "search_match_type": "exact"
}

List all surveys responses

List survey responses for a specific survey, with question text resolved server-side so callers do not have to map opaque $survey_response_<id> keys. Each row carries distinct_id, session_id, submitted_at, and an extra block (device, browser, OS, geoip, current_url, iteration) so agents can cross-pivot to recordings, persons, or paths in a single follow-up call. For person properties at event time, follow up with persons-get using the returned distinct_id — keeps scopes scoped. Use question_id + score_lte to fetch NPS detractors and similar score-filtered cohorts.

Required API key scopes

survey:readquery:read

Path parameters

  • id
    string

Query parameters

  • exclude_archived
    boolean
    Default: false
  • limit
    integer
    Default: 100
  • offset
    integer
    Default: 0
  • question_id
    string
  • score_gte
    number
  • score_lte
    number
  • since
    string
  • until
    string

Response


Example request

GET /api/projects/:project_id/surveys/:id/responses
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/responses/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "uuid": "string",
      "distinct_id": "string",
      "session_id": "string",
      "submitted_at": "2019-08-24T14:15:22Z",
      "answers": [
        {
          "question_id": "string",
          "question_index": 0,
          "question_text": "string",
          "question_type": "string",
          "answer": null
        }
      ],
      "extra": {
        "device_type": "string",
        "browser": "string",
        "os": "string",
        "geoip_country_code": "string",
        "geoip_country_name": "string",
        "geoip_city_name": "string",
        "current_url": "string",
        "iteration": "string"
      }
    }
  ],
  "has_more": true,
  "limit": 0,
  "offset": 0
}

Create surveys responses archive

Archive a single survey response.

Required API key scopes

survey:write

Path parameters

  • id
    string
  • response_uuid
    string

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
    stringnull
  • linked_flag_id
    integernull
  • linked_insight_id
    integernull
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    booleannull
  • questions
  • conditions
  • appearance
  • start_date
    stringnull
  • end_date
    stringnull
  • archived
    boolean
  • responses_limit
    integernull
  • iteration_count
    integernull
  • iteration_frequency_days
    integernull
  • iteration_start_dates
    arraynull
  • current_iteration
    integernull
  • current_iteration_start_date
    stringnull
  • response_sampling_start_date
    stringnull
  • response_sampling_interval_type
  • response_sampling_interval
    integernull
  • response_sampling_limit
    integernull
  • response_sampling_daily_limits
  • enable_partial_responses
    booleannull
  • enable_iframe_embedding
    booleannull
  • base_language
    string
  • translations
  • _create_in_folder
    string
  • form_content

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
  • response_uuid
    string

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
    stringnull
  • linked_flag_id
    integernull
  • linked_insight_id
    integernull
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    booleannull
  • questions
  • conditions
  • appearance
  • start_date
    stringnull
  • end_date
    stringnull
  • archived
    boolean
  • responses_limit
    integernull
  • iteration_count
    integernull
  • iteration_frequency_days
    integernull
  • iteration_start_dates
    arraynull
  • current_iteration
    integernull
  • current_iteration_start_date
    stringnull
  • response_sampling_start_date
    stringnull
  • response_sampling_interval_type
  • response_sampling_interval
    integernull
  • response_sampling_limit
    integernull
  • response_sampling_daily_limits
  • enable_partial_responses
    booleannull
  • enable_iframe_embedding
    booleannull
  • base_language
    string
  • translations
  • _create_in_folder
    string
  • form_content

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

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) include_per_question_stats: Optional boolean to include per-question response counts and distributions

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

Required API key scopes

survey:read

Path parameters

  • id
    string

Query parameters

  • date_from
    string
  • date_to
    string
  • include_per_question_stats
    boolean

Response


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
RESPONSE
{
  "survey_id": "string",
  "start_date": "2019-08-24T14:15:22Z",
  "end_date": "2019-08-24T14:15:22Z",
  "stats": {},
  "rates": {},
  "per_question_stats": [
    null
  ]
}

Create surveys

Stop a survey by setting end_date to the current time. No new responses are accepted after this; existing responses remain available. No-op if the survey already has an end_date in the past.

Required API key scopes

survey:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/surveys/:id/stop
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/stop/

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": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "linked_flag_id": 0,
  "linked_insight_id": 0,
  "targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "internal_targeting_flag": {
    "id": 0,
    "team_id": 0,
    "name": "string",
    "key": "string",
    "filters": {},
    "deleted": true,
    "active": true,
    "ensure_experience_continuity": true,
    "version": -2147483648,
    "evaluation_runtime": "server",
    "bucketing_identifier": "distinct_id",
    "evaluation_contexts": [
      "string"
    ]
  },
  "questions": null,
  "conditions": {},
  "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": {},
    "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": [
    {
      "property1": "string",
      "property2": "string"
    }
  ],
  "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,
  "enable_iframe_embedding": true,
  "base_language": "string",
  "translations": null,
  "user_access_level": "string",
  "form_content": null,
  "search_match_type": "exact"
}

Create surveys summarize responses

Summarize survey responses. When question_index or question_id is provided, returns a per-question theme summary using cached survey.question_summaries when fresh. When neither is provided, returns the survey-wide headline summary (delegates to summary_headline). Pass force_refresh=true in the body to bypass caches.

Required API key scopes

survey:read

Path parameters

  • id
    string

Query parameters

  • question_id
    string
  • question_index
    integer

Request parameters

  • force_refresh
    boolean
    Default: false

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 force_refresh="boolean"

Example response

Status 200 No response body

Create surveys summary headline

Required API key scopes

survey:read

Path parameters

  • id
    string

Request parameters

  • name
    string
  • description
    string
  • type
  • schedule
    stringnull
  • linked_flag_id
    integernull
  • linked_insight_id
    integernull
  • targeting_flag_id
    integer
  • targeting_flag_filters
  • remove_targeting_flag
    booleannull
  • questions
  • conditions
  • appearance
  • start_date
    stringnull
  • end_date
    stringnull
  • archived
    boolean
  • responses_limit
    integernull
  • iteration_count
    integernull
  • iteration_frequency_days
    integernull
  • iteration_start_dates
    arraynull
  • current_iteration
    integernull
  • current_iteration_start_date
    stringnull
  • response_sampling_start_date
    stringnull
  • response_sampling_interval_type
  • response_sampling_interval
    integernull
  • response_sampling_limit
    integernull
  • response_sampling_daily_limits
  • enable_partial_responses
    booleannull
  • enable_iframe_embedding
    booleannull
  • base_language
    string
  • translations
  • _create_in_folder
    string
  • form_content

Example request

POST /api/projects/:project_id/surveys/:id/summary_headline
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/summary_headline/\
	-d name="string",\
	-d type=undefined

Example response

Status 200 No response body

Retrieve surveys all activity

Required API key scopes

activity_log:read

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 question

Return a slim list of question labels for the team's surveys. Used by the frontend to resolve $survey_response_<question_id> property keys into human-readable question text without loading the full survey payload.

Required API key scopes

survey:read

Response


Example request

GET /api/projects/:project_id/surveys/question_labels
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/question_labels/

Example response

Status 200
RESPONSE
{
  "labels": [
    {
      "question_id": "string",
      "question_text": "string",
      "question_index": 0,
      "survey_id": "string",
      "survey_name": "string"
    }
  ]
}
Next page →

Community questions

Questions about this page? or post a community question.