---
title: Endpoints - APIs
description: List surveys, get a survey with its questions, and list survey responses with the Responses API endpoints.
source_url:
  html: https://docs.contentsquare.com/en/api/responses/endpoints/
  md: https://docs.contentsquare.com/en/api/responses/endpoints/index.md
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

All paths are relative to the base URL `https://api.contentsquare.com`. All endpoints require the `surveys` scope.

## Path parameters

* `project_id`  *integer*  **Required**

  The unique identifier of a Contentsquare project.

* `public_survey_id`  *string*  

  The public survey ID, in the form `survey_<uuid>`. Required for the endpoints that target a single survey.

## List surveys

GET /v1/public/projects/{project_id}/surveys

Get a paginated list of surveys for the project.

### Query parameters

* `limit`  *integer*  

  Number of surveys to return. Default 20, min 1, max 100.

* `cursor`  *string*  

  Pass `next_cursor` from the previous response to get the next page.

* `with_questions`  *boolean*  

  Include each survey's questions. Default `false`.

### Request example

```shell
curl --location 'https://api.contentsquare.com/v1/public/projects/789700/surveys?limit=20&with_questions=false' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response example (200)

```json
{
  "results": [
    {
      "id": "survey_af479a77-abea-42bf-a73f-bc02f18503bf",
      "name": "Checkout feedback",
      "is_enabled": true,
      "created_time": "2026-03-12T09:41:07Z",
      "type": "popover",
      "language": "en",
      "url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf",
      "responses_url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf/responses",
      "sentiment_analysis_enabled": true,
      "questions": null
    }
  ],
  "next_cursor": "eyJ..."
}
```

**Errors:** `400` (invalid cursor), `401`, `403`, `422`.

## Get a survey

GET /v1/public/projects/{project_id}/surveys/{public_survey_id}

Get a single survey, including its questions.

### Request example

```shell
curl --location 'https://api.contentsquare.com/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response example (200)

```json
{
  "id": "survey_af479a77-abea-42bf-a73f-bc02f18503bf",
  "name": "Checkout feedback",
  "is_enabled": true,
  "created_time": "2026-03-12T09:41:07Z",
  "type": "popover",
  "language": "en",
  "url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf",
  "responses_url": "/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf/responses",
  "sentiment_analysis_enabled": true,
  "questions": [
    {
      "id": "question_af479a77-abea-42bf-a73f-bc02f18503bf_a1b2c3",
      "type": "rating-1-5",
      "text": "How easy was it to check out?",
      "is_required": true,
      "image_url": null,
      "choices": null,
      "labels": { "low_label": "Very difficult", "high_label": "Very easy" }
    },
    {
      "id": "question_af479a77-abea-42bf-a73f-bc02f18503bf_d4e5f6",
      "type": "single-option",
      "text": "What brought you here today?",
      "is_required": false,
      "image_url": null,
      "choices": [
        { "text": "Browsing", "allow_comment": false },
        { "text": "Other", "allow_comment": true }
      ],
      "labels": null
    }
  ]
}
```

**Errors:** `400` (invalid survey ID), `401`, `403`, `404`.

### Survey object

* `id`  *string*  

  Public survey ID.

* `name`  *string*  

  Survey name.

* `is_enabled`  *boolean*  

  Whether the survey is enabled.

* `created_time`  *string (ISO 8601)*  

  Creation time (UTC).

* `type`  *string*  

  `link`, `full_screen`, `popover`, `button`, `inline`, `bubble`, or `mobile_popover`.

* `language`  *string*  

  Survey language.

* `url`  *string*  

  Path of this survey resource.

* `responses_url`  *string*  

  Path of the survey's responses.

* `sentiment_analysis_enabled`  *boolean*  

  Whether sentiment analysis is enabled.

* `questions`  *array or null*  

  Questions. `null` on the list endpoint unless `with_questions=true`.

### Question object

* `id`  *string*  

  Question ID (`question_<survey_uuid>_<short_id>`).

* `type`  *string*  

  `reaction`, `reaction-binary`, `long-text`, `short-text`, `single-option`, `multiple-option`, `email`, `rating-1-5`, `rating-1-7`, `nps`, `statement`, or `thank-you`.

* `text`  *string*  

  Question text.

* `is_required`  *boolean*  

  Whether an answer is required.

* `image_url`  *string or null*  

  Image attached to the question.

* `choices`  *array or null*  

  For `single-option` and `multiple-option` questions: `text` and `allow_comment` for each choice.

* `labels`  *object or null*  

  For scale questions: `low_label` and `high_label`.

## List survey responses

GET /v1/public/projects/{project_id}/surveys/{public_survey_id}/responses

Get a paginated list of responses for a survey.

### Query parameters

* `limit`  *integer*  

  Number of responses to return. Default 20, min 1, max 100.

* `cursor`  *string*  

  Pass `next_cursor` from the previous response to get the next page.

### Request example

```shell
curl --location 'https://api.contentsquare.com/v1/public/projects/789700/surveys/survey_af479a77-abea-42bf-a73f-bc02f18503bf/responses?limit=20' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response example (200)

```json
{
  "results": [
    {
      "id": "response_62e88f7c-7346-495a-a442-6567e175ab85",
      "answers": [
        {
          "question_id": "question_af479a77-abea-42bf-a73f-bc02f18503bf_a1b2c3",
          "answer": "2",
          "comment": "Too many form fields.",
          "tags": [{ "name": "checkout" }],
          "sentiment": "negative"
        }
      ],
      "browser": "Chrome",
      "country": "FR",
      "created_time": "2026-10-20T14:05:11Z",
      "updated_time": "2026-10-20T14:06:02Z",
      "device": "desktop",
      "visitor_id": "XXXX",
      "is_complete": true,
      "os": "macOS",
      "recording_url": "https://app.contentsquare.com/...",
      "response_origin_url": "https://www.example.com/checkout",
      "user_attributes": [{ "name": "plan", "value": "premium" }],
      "window_size": { "width": 1440, "height": 900 }
    }
  ],
  "next_cursor": null
}
```

**Errors:** `400` (invalid survey ID or cursor), `401`, `403`, `404`, `422`.

### Response object

* `id`  *string*  

  Unique identifier of the response.

* `answers`  *array*  

  The answers to the survey questions (see the answer object below).

* `browser`  *string*  

  Respondent's browser. Empty string if unknown.

* `os`  *string*  

  Respondent's operating system. Empty string if unknown.

* `country`  *string*  

  Respondent's country, as an ISO 3166-1 alpha-2 code. Empty string if unknown.

* `device`  *string*  

  `desktop`, `mobile`, or `tablet`.

* `visitor_id`  *string*  

  Visitor identifier.

* `is_complete`  *boolean*  

  Whether the respondent completed the survey.

* `created_time`  *string (ISO 8601)*  

  Time the response was submitted.

* `updated_time`  *string (ISO 8601)*  

  Time the response was last updated.

* `recording_url`  *string or null*  

  Link to the Session Replay, if available.

* `response_origin_url`  *string*  

  Page where the survey was answered.

* `user_attributes`  *array*  

  User attributes, each with a `name` and a `value` (boolean, number, string, datetime, or `null`).

* `window_size`  *object*  

  `width` and `height` of the respondent's window, in pixels. Each can be `null`.

### Answer object

* `question_id`  *string*  

  ID of the answered question.

* `answer`  *string*  

  The respondent's answer, as a string.

* `comment`  *string or null*  

  Optional comment added by the respondent.

* `tags`  *array*  

  Tags applied to the answer, each as an object with a `name`.

* `sentiment`  *string or null*  

  `positive`, `negative`, or `neutral`. `null` if there is no sentiment or sentiment analysis is disabled.


```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"Endpoints","description":"List surveys, get a survey with its questions, and list survey responses with the Responses API endpoints.","url":"https://docs.contentsquare.com/en/api/responses/endpoints/","inLanguage":"en","dateModified":"2026-11-04T13:03:38+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}}
```