> ## 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.

# Get survey responses

> Returns paginated individual responses for a survey. Each response includes the respondent's answer, written explanation, demographic traits, and media (if applicable). Use `question_id` to filter responses to a specific question, `text` to search response explanations, and `traits` to filter by respondent demographics.



## OpenAPI

````yaml /docs/api-reference/openapi.json get /surveys/{id}/responses
openapi: 3.1.0
info:
  title: PickFu API
  version: 1.0.0
  description: >-
    The PickFu API enables programmatic access to create surveys, retrieve
    results, and integrate PickFu into your workflows.


    ## Overview


    PickFu helps you get instant consumer feedback through surveys. With the
    API, you can:


    - Create surveys programmatically

    - Retrieve survey results and respondent data

    - Target specific audiences with demographic traits

    - Integrate PickFu into your product development workflow


    ## Rate Limits


    Selected endpoints (currently the CSV export endpoints) enforce per-caller
    rate limits and return `429 Too Many Requests` when exceeded. See each
    endpoint description for its specific budget.


    ## Authentication


    All API requests require a Bearer token — either an API key or an OAuth 2.0
    access token. See the [Authentication
    guide](https://www.pickfu.com/docs/developers/authentication) for details.
  contact:
    name: PickFu Support
    email: support@pickfu.com
    url: https://www.pickfu.com
servers:
  - url: https://api.pickfu.com/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Surveys
    description: >-
      Create, retrieve, update, and publish surveys. Surveys are the core
      resource — each contains one or more questions with answer options.
  - name: Responses
    description: >-
      Retrieve individual responses (answers) for a survey, with pagination and
      per-question filtering.
  - name: Tags
    description: Organize surveys with tags. Tags are scoped to your team/account.
  - name: Projects
    description: >-
      Organize surveys into projects. Projects group related surveys and can be
      bookmarked or archived.
  - name: Traits
    description: >-
      Audience targeting and reporting traits used to reach specific
      demographics and segment survey results.
  - name: Playbooks
    description: >-
      Discover and retrieve step-by-step research playbooks. Each playbook is a
      structured sequence of polls designed for a specific research goal.
  - name: Help
    description: Search the PickFu help center for articles and guides.
  - name: Media
    description: >-
      Generate images from text prompts and upload media files to the PickFu
      CDN.
  - name: Semantic Search
    description: >-
      Search completed surveys in your enrolled team account by meaning and
      answer evidence.
paths:
  /surveys/{id}/responses:
    get:
      tags:
        - Responses
      summary: Get survey responses
      description: >-
        Returns paginated individual responses for a survey. Each response
        includes the respondent's answer, written explanation, demographic
        traits, and media (if applicable). Use `question_id` to filter responses
        to a specific question, `text` to search response explanations, and
        `traits` to filter by respondent demographics.
      operationId: getSurveyResponses
      parameters:
        - schema:
            type: integer
            minimum: 1
            default: 1
          in: query
          name: page
          required: false
          description: Page number
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          in: query
          name: limit
          required: false
          description: Results per page (1-100)
        - schema:
            type: string
          in: query
          name: question_id
          required: false
          description: Filter responses to a specific question by its GUID
        - schema:
            type: string
          in: query
          name: language
          required: false
          description: Language code for response translations (e.g. ES, FR, DE)
        - schema:
            type: string
            maxLength: 255
          in: query
          name: text
          required: false
          description: Keyword to filter responses by explanation text (case-insensitive)
        - schema:
            type: string
          in: query
          name: traits
          required: false
          description: >-
            Comma-separated trait value permalinks to filter by respondent
            demographics (e.g. "male,age-25-34"). Values within the same trait
            use OR logic; across different traits use AND logic.
        - schema:
            type: string
          in: path
          name: id
          required: true
          description: Survey GUID
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  currency:
                    type: string
                    description: ISO 4217 currency derived from the survey target country
                  data:
                    type: array
                    description: List of individual responses
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Response ID
                        pinned:
                          type: boolean
                          description: Whether the response is pinned
                        explanation:
                          type:
                            - string
                            - 'null'
                          description: Written explanation from the respondent
                        translation:
                          type:
                            - string
                            - 'null'
                          description: Translated explanation text
                        chosenOption:
                          type:
                            - string
                            - 'null'
                          description: Label of the option chosen by the respondent
                        selectedOptions:
                          type:
                            - array
                            - 'null'
                          description: >-
                            Labels of options selected by the respondent for
                            multi-select questions
                          items:
                            type: string
                        score:
                          type:
                            - number
                            - 'null'
                          description: >-
                            Rating score (for emoji_rating, star_rating question
                            types)
                        clicks:
                          type:
                            - array
                            - 'null'
                          description: Click coordinates for click_test questions
                          items:
                            type: object
                            properties:
                              number:
                                type: number
                                description: Click sequence number
                              xCoord:
                                type: number
                                description: X coordinate of the click
                              yCoord:
                                type: number
                                description: Y coordinate of the click
                        ranking:
                          type:
                            - array
                            - 'null'
                          description: >-
                            Respondent's ranking of options for ranked question
                            types. Each entry pairs a rank (1 = top pick) with
                            the option label.
                          items:
                            type: object
                            properties:
                              rank:
                                type: number
                                description: Rank position (1 = respondent's top pick)
                              option:
                                type:
                                  - string
                                  - 'null'
                                description: Option label at this rank
                        media:
                          type:
                            - string
                            - 'null'
                          description: Media URL (for screen_recording question types)
                        mediaTranscription:
                          type:
                            - string
                            - 'null'
                          description: Transcription of the recorded media
                        matchup:
                          type:
                            - object
                            - 'null'
                          description: Head-to-head matchup pairing shown to the respondent
                          properties:
                            option1:
                              type: string
                              description: First option in the matchup
                            option2:
                              type: string
                              description: Second option in the matchup
                        statements:
                          type:
                            - array
                            - 'null'
                          description: >-
                            Per-statement responses for likert question types.
                            Each entry pairs a statement with the numeric value
                            the respondent picked on the configured scale.
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: GUID of the statement (the question option)
                              statement:
                                type:
                                  - string
                                  - 'null'
                                description: Statement text
                              value:
                                type: number
                                description: >-
                                  Numeric value the respondent picked on the
                                  Likert scale (1..N for the configured scale)
                        prices:
                          type:
                            - object
                            - 'null'
                          description: >-
                            Van Westendorp price-sensitivity responses. Four
                            numeric prices the respondent provided for the four
                            standardized PSM questions.
                          properties:
                            tooCheap:
                              type: number
                              description: >-
                                Price at which the product would be so cheap
                                that quality is questionable
                            bargain:
                              type: number
                              description: Price at which the product would be a bargain
                            expensive:
                              type: number
                              description: >-
                                Price at which the product starts to feel
                                expensive but is still worth considering
                            tooExpensive:
                              type: number
                              description: >-
                                Price at which the product would be too
                                expensive to consider
                        respondent:
                          type: array
                          description: Demographic traits of the respondent
                          items:
                            type: object
                            properties:
                              trait:
                                type: string
                                description: Trait category name
                              value:
                                type: string
                                description: Trait value
                        question_id:
                          type:
                            - string
                            - 'null'
                          description: >-
                            GUID of the question this response belongs to (for
                            multi-question surveys)
                  pagination:
                    type: object
                    description: Pagination metadata
                    properties:
                      page:
                        type: number
                        description: Current page number
                      limit:
                        type: number
                        description: Results per page
                      total:
                        type: number
                        description: Total number of results
                      totalPages:
                        type: number
                        description: Total number of pages
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                  error:
                    type: string
                  message:
                    type: string
        '422':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  code:
                    type: string
                  availableLanguages:
                    type: array
                    items:
                      type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth2 access token obtained via the authorization flow. Include in the
        Authorization header as: `Bearer {access_token}`

````

## Related topics

- [International surveys and translation](https://www.pickfu.com/docs/guides/international-surveys.md)
- [PickFu MCP server for Claude, Cursor, and ChatGPT](https://www.pickfu.com/docs/integrations/mcp-server.md)
- [Get survey](https://www.pickfu.com/docs/api-reference/surveys/get-survey.md)
- [Get survey publication schedule](https://www.pickfu.com/docs/api-reference/surveys/get-survey-publication-schedule.md)
- [Can I get a refund for my survey, or subscription?](https://www.pickfu.com/help/can-i-get-a-refund-for-my-poll-survey-or-subscription.md)


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