> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/api-v3/objects-schema/survey-question-object.md).

# Survey Question Object

## Survey Question Object

| Field            | Type    | Description                                                                                                                    |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`           | String  | Question UUID.                                                                                                                 |
| `position`       | Integer | Order within the survey (ascending).                                                                                           |
| `label`          | String  | The question text shown to subscribers.                                                                                        |
| `required`       | Boolean | Whether an answer is required.                                                                                                 |
| `type`           | String  | `text_input`, `single_select`, `multi_select`, or `checkbox`.                                                                  |
| `options`        | Array   | The selectable options, each `{ "id", "label" }`. Present only for `single_select` and `multi_select`.                         |
| `max_selections` | Integer | How many options a subscriber may pick. Present only for a `multi_select` question with a cap. No key means no limit.          |
| `condition`      | Object  | Shows the question only for some answers: `{ "question", "value" }`. Present only when the question is conditional. See below. |
| `stats`          | Object  | Per-option answer distribution. Present only with `expand=stats`, and only for select questions.                               |

**`condition`**

| Field      | Type   | Description                                                                       |
| ---------- | ------ | --------------------------------------------------------------------------------- |
| `question` | Object | The condition's question, as a Survey Question Object.                            |
| `value`    | String | The selected option's label. Missing when the condition's question is a checkbox. |

If the condition's question was deleted, `condition` is `{}`. If the option it used was removed, `condition` has no `value`.

You write a condition differently. Send `{ "question_uuid", "value" }`. See [Conditions](https://docs.sparkloop.app/api-v3/endpoints/publications/tools/surveys.md#conditions).

**`stats`** (only with `expand=stats`)

| Field           | Type    | Description                                                                                                                                                                                                                                                                                                                           |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total_answers` | Integer | Number of respondents to this question.                                                                                                                                                                                                                                                                                               |
| `distribution`  | Array   | One entry for each current option, even when nobody picked it (`count` 0). Each entry is `{ "value": <option label>, "count": <times picked> }`. An answer to an option you have since removed or renamed adds an extra entry under the old label. On a `multi_select` question `count` can be higher than the number of respondents. |

**Example (`single_select`, `expand=stats`)**

```json
{
  "uuid": "survey_question_9f8e7d6c1a2b",
  "position": 1,
  "label": "What best describes your role?",
  "required": true,
  "type": "single_select",
  "options": [
    { "id": "opt_1a2b3c4d5e6f", "label": "Founder" },
    { "id": "opt_2b3c4d5e6f7a", "label": "Engineer" },
    { "id": "opt_3c4d5e6f7a8b", "label": "Marketer" },
    { "id": "opt_4d5e6f7a8b9c", "label": "Other" }
  ],
  "stats": {
    "total_answers": 1800,
    "distribution": [
      { "value": "Founder", "count": 540 },
      { "value": "Engineer", "count": 720 },
      { "value": "Marketer", "count": 360 },
      { "value": "Other", "count": 180 }
    ]
  }
}
```
