Question results

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

curl https://api.pickfu.com/v2/surveys/srv_8f3a1c2e9b7d4f6a8c0e1b2d3f4a5c6e \
  -H "Authorization: Bearer sk_live_..."

{
  "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 before you treat the winner as final.

Fields

object | null

required

Aggregated results for this question.

Show properties

integer

required

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

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.

number

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

array

required

One row per option, ordered by rank.

Show properties

string

required

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

string | null

required

The option’s label.

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.

number | null

required

The option’s score. See Scoring by question type.

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.

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.

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.

API Reference

API v2

Surveys

Responses

Tags

Traits

Playbooks

Projects

Media

Mockup templates

Account

Question results

Example

When results are available

Fields

Scoring by question type

​Example

​When results are available

​Fields

​Scoring by question type

Example

When results are available

Fields

Scoring by question type