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

# Question results

> Read per-question vote counts, scores, ranks, and winners inline on the v2 survey resource, and learn how each question type is scored.

Every question in a full v2 survey resource carries a `results` object with a summary of how respondents answered. Use it when you need the headline numbers, such as the winner, each option's score, or a rating average, without paging through individual responses.

The `results` summary is included wherever v2 returns the full survey: `GET /v2/surveys/{id}`, `POST /v2/surveys`, `PATCH /v2/surveys/{id}`, `POST /v2/surveys/{id}/publish`, and `POST /v2/surveys/{id}/stop`. For individual answers, use `GET /v2/surveys/{id}/responses` or the CSV export instead.

## Example

```bash theme={null}
curl https://api.pickfu.com/v2/surveys/srv_8f3a1c2e9b7d4f6a8c0e1b2d3f4a5c6e \
  -H "Authorization: Bearer sk_live_..."
```

```json theme={null}
{
  "id": "srv_8f3a1c2e9b7d4f6a8c0e1b2d3f4a5c6e",
  "status": "completed",
  "questions": [
    {
      "object": "question",
      "id": "qst_1b2c3d4e5f60718293a4b5c6d7e8f901",
      "type": "head_to_head",
      "prompt": "Which cover do you prefer?",
      "options": [
        { "id": "opt_a1b2c3d4e5f60718293a4b5c6d7e8f90", "label": "Blue cover" },
        { "id": "opt_b2c3d4e5f60718293a4b5c6d7e8f901a", "label": "Red cover" }
      ],
      "results": {
        "totalResponses": 50,
        "winningOptionId": "opt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
        "options": [
          {
            "id": "opt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
            "label": "Blue cover",
            "votes": 32,
            "score": 64,
            "percentage": 64,
            "rank": 1,
            "isWinner": true
          },
          {
            "id": "opt_b2c3d4e5f60718293a4b5c6d7e8f901a",
            "label": "Red cover",
            "votes": 18,
            "score": 36,
            "percentage": 36,
            "rank": 2,
            "isWinner": false
          }
        ]
      }
    }
  ]
}
```

The survey and question objects are trimmed to the fields relevant to results.

## When results are available

* `results` is `null` until the question has at least one eligible response.
* While a survey is still collecting (`status: "in-progress"`), `results` holds partial aggregates. The numbers change as more responses arrive.
* `winningOptionId` and `isWinner` are set only after PickFu persists a winner for the question. Until then, `winningOptionId` is `null` and every `isWinner` is `false`. A `rank` of `1` does not by itself mean the option won.
* `results` is `null` for question types that don't produce an aggregate summary, and when the aggregates for a question are unavailable.

Wait for `status: "completed"` or the `survey.completed` [webhook](/docs/api-reference/v2/webhooks.md) before you treat the winner as final.

## Fields

**results** `object | null` *required*

Aggregated results for this question.

**properties**

**totalResponses** `integer` *required*

Number of eligible responses, capped at the survey's sample size.

**winningOptionId** `string | null` *required*

The `opt_…` ID of the persisted winner. It matches one of the question's `options[].id` values. `null` until a winner is decided, and always `null` for rating questions.

**averageScore** `number`

Average star or emoji rating. Present only on rating questions. For ratings, `options` is an empty array.

**options** `array` *required*

One row per option, ordered by `rank`.

**properties**

**id** `string` *required*

The option's public `opt_…` ID. It matches the question's `options[].id`.

**label** `string | null` *required*

The option's label.

**votes** `integer` *required*

Votes for the option. For ranked questions, this is the vote count in the final runoff round. For round-robin questions, this is the number of matchups the option won.

**score** `number | null` *required*

The option's score. See [Scoring by question type](#scoring-by-question-type).

**percentage** `integer | null` *required*

`votes / totalResponses × 100`, rounded to a whole number from the unrounded ratio. It can differ by one from rounding the displayed `score`. For round-robin, it is `score` rounded instead, and `null` when `score` is `null`.

**rank** `integer | null` *required*

The option's position, starting at `1`. PickFu uses the persisted rank when one exists. Otherwise, options are ordered by score (highest first), then by label.

**isWinner** `boolean` *required*

`true` only for the option whose ID equals `winningOptionId`.

## Scoring by question type

| Question type | `votes` | `score` |
| - | - | - |
| Head-to-head, single-select, multi-select | Votes for the option | `votes / totalResponses × 100`, rounded to 1 decimal place |
| Ranked | Final runoff votes | `votes / totalResponses × 100`, rounded to 2 decimal places |
| Round-robin | Matchups won | The persisted score when present, otherwise win rate: `wins / (wins + losses) × 100`, rounded to 2 decimal places. `null` when the option has no matchups. |
| Rating | Not applicable | No option rows. Read `averageScore` instead. |

Multi-select respondents can pick more than one option, so multi-select scores don't need to add up to 100.


## Related topics

- [What is a Screen Recording question and when to use it?](/help/what-is-a-screen-recording-poll-and-when-should-i-use-it.md)
- [What is a Head-to-Head question and when should I use it?](/help/what-is-a-head-to-head-poll-and-when-should-i-use-it.md)
- [What is an Open-ended question and when should I use it?](/help/what-is-an-open-ended-poll-and-when-should-i-use-it.md)
- [What is a Ranked question and when should I use it?](/help/what-is-a-ranked-poll-and-when-should-i-use-it.md)
- [What is a survey and when should I build one?](/help/what-is-a-survey-and-when-should-i-build-one.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.