openapi: 3.2.0
info:
  contact:
    email: support@sprig.com
    name: Support
  description: Sprig is a continuous product research tool that helps you automatically capture the user insights you need to consistently improve your product, user experience, marketing, and more.
  title: Sprig Responses API
  version: 2.2.1
servers:
- url: https://api.sprig.com
tags:
- name: Responses
paths:
  /v1/responses:
    get:
      description: Use this endpoint to retrieve responses from your studies. This endpoint allows you to retrieve up to 1000 responses at a time.
      operationId: get-v1-responses
      parameters:
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/end'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/sid'
      - $ref: '#/components/parameters/Authorization-Bearer'
      - description: true/false(default). If true, the API will return visitorSnapshots, which contains all events, attributes, triggeringEvent, and eventProperties set for the visitor at the time of survey delivery.
        in: query
        name: with_snapshots
        schema:
          type: boolean
      - description: true/false (default). If true, the API will return the page URL from which the survey was taken.
        in: query
        name: with_urls
        schema:
          type: boolean
      - description: true/false (default). If true, the API will return the metadata JSON blob containing details available from the client.
        in: query
        name: with_meta
        schema:
          type: boolean
      - description: true/false (default). If true, the API will return any custom metadata associated with the response (applicable to link platform surveys only).
        in: query
        name: with_custom_metadata
        schema:
          type: boolean
      - description: true/false (default). If true, the API will return the responses that have been previously deleted.
        in: query
        name: with_deleted_responses
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              examples:
                consent/legal example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2023-10-19T17:04:26.253Z'
                      externalUserId: null
                      questionId: 2
                      questionText: Consent / Legal Question
                      questionType: CONSENTLEGAL
                      response:
                        submitted: true
                      responseGroupUid: 9fa86a17-82b1-423a-979a-30ee35ada562
                      surveyId: 1
                      updatedAt: '2023-10-19T17:04:26.253Z'
                      visitorId: 0
                      visitorUuid: 3b7b4806-c082-4f0c-a8f0-b869121f47cb
                likert example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2024-01-26T18:58:32.835Z'
                      questionId: 2
                      questionText: How interested are you in using Sprig to capture passive in-product feedback?
                      questionType: LIKERT
                      response: 5
                      responseGroupUid: b96b109f-040c-412a-9ca4-4d694ccaec90
                      surveyId: 1
                      updatedAt: '2024-01-26T18:58:32.835Z'
                      visitorId: 0
                      visitorUuid: ba050493-0292-4099-9262-8e18c7406e81
                matrix example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2024-01-26T18:59:12.629Z'
                      externalUserId: null
                      questionId: 2
                      questionText: How important are the following features?
                      questionType: MATRIX
                      response:
                        Ability to do x: 3 - Neutral
                        Create a bad surveys: 1 - Not Important
                        Display something on something else: '2'
                        Receiving high quality responses: 5 - Very Important
                      responseGroupUid: 45b8d797-c326-4824-bc24-7b2c54315ef2
                      surveyId: 1
                      updatedAt: '2024-01-26T18:59:12.629Z'
                      visitorId: 0
                      visitorUuid: ba050493-0292-4099-9262-8e18c7406e81
                multiple choice example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2022-07-27T21:12:10.875Z'
                      externalUserId: '2603'
                      questionId: 2
                      questionText: What options did you prefer?
                      questionType: MULTIPLECHOICE
                      response: Option 2
                      responseGroupUid: b96b109f-040c-412a-9ca4-4d694ccaec90
                      selectedIndexes: 2
                      surveyId: 1
                      updatedAt: '2022-07-27T21:12:10.875Z'
                      visitorId: 0
                      visitorUuid: ba050493-0292-4099-9262-8e18c7406e81
                multiple select example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2022-07-27T21:12:13.159Z'
                      externalUserId: '2603'
                      questionId: 201373
                      questionText: What options did you prefer?
                      questionType: MULTIPLESELECT
                      response: Option 2
                      responseGroupUid: b96b109f-040c-412a-9ca4-4d694ccaec90
                      selectedIndexes:
                      - 2
                      - 3
                      - 4
                      surveyId: 1
                      updatedAt: '2022-07-27T21:12:13.159Z'
                      visitorId: 0
                      visitorUuid: ba050493-0292-4099-9262-8e18c7406e81
                nps example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2023-10-13T21:46:25.026Z'
                      externalUserId: null
                      questionId: 2
                      questionText: NPS Question
                      questionType: NPS
                      response: 5
                      responseGroupUid: 9d52a356-7b13-41ce-b0b4-95761512caf6
                      surveyId: 1
                      updatedAt: '2023-10-13T21:50:12.658Z'
                      visitorId: 0
                      visitorUuid: ca0af590-f7d4-47b9-b1b4-38dad61e1755
                open text example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2024-01-26T18:59:45.553Z'
                      externalUserId: null
                      questionId: 2
                      questionText: What questions do you have about Feedback button surveys?
                      questionType: OPEN
                      response: So many questions. I would love to follow up with someone to discuss.
                      responseGroupUid: 234ce7e2-531b-4549-a0f7-faf99583e6ea
                      surveyId: 1
                      updatedAt: '2024-01-26T18:59:45.553Z'
                      visitorId: 0
                      visitorUuid: b8e8107b-aa0a-4126-a89a-cfc735b44a77
                texturl prompt example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2023-12-14T18:04:28.573Z'
                      externalUserId: null
                      questionId: 2
                      questionText: Explore the Create with AI feature. Pause once you've generated ideas and click Next.
                      questionType: TEXTURLPROMPT
                      response: null
                      responseGroupUid: 1b0e6ae6-8167-4ed0-a275-4a9cdb422522
                      surveyId: 1
                      updatedAt: '2023-12-14T18:04:28.573Z'
                      visitorId: 0
                      visitorUuid: f723900e-c4ac-4f69-b9a9-07400dd6076f
                videovoice example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2022-03-18T05:47:56.857Z'
                      externalUserId: null
                      questionId: 2
                      questionText: Sprig has a video question for you
                      questionType: VIDEOVOICE
                      response:
                        downloadUrl: https://stream.mux.com/random_id/high.mp4
                        duration: 42.923667
                        mediaType: video
                        transcription: Hey there! I hope these docs are helpful and informative. If you have any questions, please reach out to your dedicated Customer Support Manager or feel free to email us at support@sprig.com
                        updatedAt: '2023-10-18T05:50:57.208Z'
                        uploadId: uploadId
                        videoUrl: https://stream.mux.com/random_id.video
                      responseGroupUid: f723900e-c4ac-4f69-b9a9-07400dd6076f
                      surveyId: 1
                      updatedAt: '2022-03-18T05:52:07.910Z'
                      visitorId: 0
                      visitorUuid: d86c1335-21ca-4417-9e00-6370db899727
                with custom metadata example:
                  value:
                    cursor: null
                    data:
                    - createdAt: '2023-07-20T00:41:57.074Z'
                      customMetadata: {}
                      externalUserId: null
                      questionId: 0
                      questionText: How likely are you to recommend Your Product to a friend or colleague?
                      questionType: NPS
                      response: 9
                      responseGroupUid: 6bc0c9b7-af36-4d81-a03c-b600fd23a5e5
                      surveyId: 0
                      updatedAt: '2023-07-20T00:41:57.074Z'
                      visitorId: 0
                      visitorUuid: ab85c1ab-59fd-4855-b501-a7ab80419cf8
                with deleted responses example:
                  value:
                    cursor: null
                    data:
                    - createdAt: '2023-07-20T00:41:57.074Z'
                      deletedAt: '2023-07-20T00:41:57.074Z'
                      externalUserId: null
                      questionId: 0
                      questionText: How likely are you to recommend Your Product to a friend or colleague?
                      questionType: NPS
                      response: 9
                      responseGroupUid: 6bc0c9b7-af36-4d81-a03c-b600fd23a5e5
                      surveyId: 0
                      updatedAt: '2023-07-20T00:41:57.074Z'
                      visitorId: 0
                      visitorUuid: ab85c1ab-59fd-4855-b501-a7ab80419cf8
                with meta example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2023-05-29T19:57:55.291Z'
                      externalUserId: null
                      meta:
                        browser: Chrome
                        client:
                          height: 969
                          width: 1920
                        href: https://a.sprig.com/yoursurvey
                        language: en-US
                        os: Windows
                        screen:
                          height: 1080
                          width: 1920
                        userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36
                      questionId: 0
                      questionText: How likely are you to recommend Sprig to a friend or colleague?
                      questionType: NPS
                      response: 9
                      responseGroupUid: 51e167b8-f2b0-44d0-9aa3-bec160e9e1cd
                      surveyId: 0
                      updatedAt: '2023-05-29T19:57:55.291Z'
                      visitorId: 0
                      visitorUuid: f0844b38-5969-483d-8963-4b240ce8ef80
                with snapshots example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2022-07-20T00:41:57.074Z'
                      externalUserId: null
                      questionId: 0
                      questionText: How likely are you to recommend Luke Test to a friend or colleague?
                      questionType: NPS
                      response: 9
                      responseGroupUid: 6bc0c9b7-af36-4d81-a03c-b600fd23a5e5
                      surveyId: 0
                      updatedAt: '2022-07-20T00:41:57.074Z'
                      visitorId: 0
                      visitorSnapshot:
                        attributes: {}
                        eventProperties: {}
                        events: {}
                        externalUserId: null
                        responseGroupUid: 18e38583-d6b6-4629-b2ce-c51072308f98
                        triggeringEvent: event
                        visitorId: visitor-id
                      visitorUuid: ab85c1ab-59fd-4855-b501-a7ab80419cf8
                with urls example:
                  value:
                    cursor: cursor
                    data:
                    - createdAt: '2023-05-29T19:58:23.028Z'
                      externalUserId: null
                      questionId: 0
                      questionText: Text Url Prompt Question
                      questionType: TEXTURLPROMPT
                      response: null
                      responseGroupUid: 52845ce4-c41f-484d-8f47-5702cb49f3f5
                      surveyId: 0
                      updatedAt: '2023-05-29T19:58:23.028Z'
                      url: https://a.sprig.com/yoursurvey
                      visitorId: 0
                      visitorUuid: c180328a-5cc1-4e76-a942-3363412fed51
                    - createdAt: '2023-05-29T19:58:24.188Z'
                      externalUserId: null
                      questionId: 1
                      questionText: Consent Legal Questuion
                      questionType: CONSENTLEGAL
                      response:
                        submitted: true
                      responseGroupUid: 52845ce4-c41f-484d-8f47-5702cb49f3f5
                      surveyId: 0
                      updatedAt: '2023-05-29T19:58:24.188Z'
                      url: https://a.sprig.com/yoursurvey
                      visitorId: 0
                      visitorUuid: c180328a-5cc1-4e76-a942-3363412fed51
                maxDiff example:
                  summary: maxDiff example
                  value:
                    cursor: null
                    data:
                    - visitorId: 0
                      surveyId: 30405
                      questionId: 239621
                      updatedAt: '2025-11-20T17:46:41.772Z'
                      createdAt: '2025-11-20T17:46:19.740Z'
                      responseGroupUid: 52558537-3c62-4840-a6da-bf02e2dbe0e6
                      response:
                      - - id: 161748
                          option: Sharks
                          selected: right
                        - id: 161745
                          option: Puppies
                          selected: left
                        - id: 161749
                          option: Goldfish
                          selected: null
                        - id: 161747
                          option: Parrots
                          selected: null
                      - - id: 161745
                          option: Puppies
                          selected: null
                        - id: 161749
                          option: Goldfish
                          selected: null
                        - id: 161746
                          option: Kittens
                          selected: left
                        - id: 161750
                          option: Snakes
                          selected: right
                      - - id: 161749
                          option: Goldfish
                          selected: null
                        - id: 161746
                          option: Kittens
                          selected: left
                        - id: 161748
                          option: Sharks
                          selected: right
                        - id: 161747
                          option: Parrots
                          selected: null
                      - - id: 161745
                          option: Puppies
                          selected: left
                        - id: 161748
                          option: Sharks
                          selected: null
                        - id: 161747
                          option: Parrots
                          selected: null
                        - id: 161746
                          option: Kittens
                          selected: right
                      - - id: 161750
                          option: Snakes
                          selected: right
                        - id: 161746
                          option: Kittens
                          selected: null
                        - id: 161745
                          option: Puppies
                          selected: left
                        - id: 161749
                          option: Goldfish
                          selected: null
                      questionText: Sample MaxDiff Data
                      externalUserId: ''
                      partnerAnonymousId: ''
                      visitorUuid: 47a5cb1c-3548-48d8-8658-6d8356d124db
                      questionType: MAXDIFF
                rank order example:
                  summary: rank order example
                  value:
                    cursor: null
                    data:
                    - visitorId: 0
                      surveyId: 30402
                      questionId: 239618
                      updatedAt: '2025-11-19T21:56:36.467Z'
                      createdAt: '2025-11-19T21:56:36.467Z'
                      responseGroupUid: 67d166b1-0691-4577-8909-8007131dbb7b
                      response:
                        apple: 1
                        ball: 2
                        questions: 3
                      questionText: rank it
                      externalUserId: ''
                      partnerAnonymousId: ''
                      visitorUuid: 627d9207-554a-41dc-97ae-f2c44582ce83
                      questionType: RANKORDER
              schema:
                description: ''
                properties:
                  cursor:
                    minLength: 1
                    type: string
                  data:
                    items:
                      properties:
                        createdAt:
                          minLength: 1
                          type: string
                        customMetadata:
                          description: The custom metadata of your sprig survey. Only returned when with_custom_metadata is true
                          type: object
                        deletedAt:
                          description: Only returned when with_deleted_responses is true
                          minLength: 1
                          nullable: true
                          type: string
                        externalUserId:
                          minLength: 1
                          nullable: true
                          type: string
                        meta:
                          description: The metadata of your sprig survey. Only returned when with_meta is true
                          properties:
                            browser:
                              minLength: 1
                              type: string
                            client:
                              properties:
                                height:
                                  type: integer
                                width:
                                  type: integer
                              type: object
                            href:
                              minLength: 1
                              type: string
                            language:
                              minLength: 1
                              type: string
                            os:
                              minLength: 1
                              type: string
                            screen:
                              properties:
                                height:
                                  type: integer
                                width:
                                  type: integer
                              type: object
                            userAgent:
                              minLength: 1
                              type: string
                          type: object
                        questionId:
                          type: number
                        questionText:
                          minLength: 1
                          type: string
                        questionType:
                          minLength: 1
                          type: string
                        response:
                          anyOf:
                          - type: string
                          - type: integer
                          - type: object
                          - type: array
                          - type: 'null'
                          description: The response field can return multiple data types (string, integer, object, array, or null) depending on the question type. Please refer to the examples for more information.
                        responseGroupUid:
                          minLength: 1
                          type: string
                        selectedIndexes:
                          anyOf:
                          - type: integer
                          - type: array
                          description: The selectedIndexes field returns one of two data types depending on question type. For multiple choice questions, it returns an integer. For multiple select questions, it returns an array of integers. Please refer to the examples for more information.
                        surveyId:
                          type: number
                        updatedAt:
                          minLength: 1
                          type: string
                        url:
                          description: The url of your sprig survey. Only returned when with_urls is true
                          minLength: 1
                          type: string
                        visitorId:
                          type: number
                        visitorSnapshot:
                          description: The visitor event, attribute, event property data of a Sprig survey response. Only returned when with_snapshots is true
                          properties:
                            attribtues:
                              type: object
                            eventProperties:
                              type: object
                            events:
                              type: object
                            responseGroupUid:
                              type: string
                            triggeringEvent:
                              type: string
                            visitorId:
                              type: string
                          type: object
                        visitorUuid:
                          minLength: 1
                          type: string
                      type: object
                    minItems: 1
                    type: array
                    uniqueItems: true
                type: object
                x-examples:
                  example-1:
                    cursor: Y3JlYXRlZEF0OjE1ODA5MzAyNzg2OTY=
                    data:
                    - createdAt: '2020-02-21T23:33:23.248Z'
                      externalUserId: 35c52a35-2f59-4d2f-946c-36d19137a95a
                      questionId: 369
                      questionText: What would make Sprig more valuable for you?
                      questionType: OPEN
                      response: A more robust data export api
                      responseGroupUid: 8f41fd42-a034-49b6-8a7f-8a231fd6b49a
                      surveyId: 227
                      updatedAt: '2020-02-21T23:33:23.248Z'
                      visitorId: 19720642
                    - createdAt: '2020-10-28T21:37:31.028Z'
                      externalUserId: null
                      questionId: 226
                      questionText: What would make Sprig more valuable for you?
                      questionType: OPEN
                      response: Something something cheeseburgers
                      responseGroupUid: 18e38583-d6b6-4629-b2ce-c51072308f98
                      surveyId: 154
                      updatedAt: '2020-10-28T21:37:31.028Z'
                      visitorId: 33094801
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      summary: Retrieve Responses
      tags:
      - Responses
components:
  responses:
    '500':
      description: Something went wrong on Sprig's side. These are very rare :)
    '403':
      description: You may have an invalid or missing API key and you should check your authorization header. There is no message with this status code.
    '400':
      content:
        application/json:
          schema:
            properties:
              error:
                type: string
      description: Bad Request
    '429':
      description: Your application has made too many requests in too short a time.
    '404':
      description: Not Found
  parameters:
    sid:
      description: An integer id for a specific Survey
      in: query
      name: sid
      required: false
      schema:
        type: integer
    start:
      description: The earliest creation data for a generated theme to return, represented as milliseconds from epoch time
      in: query
      name: start
      required: false
      schema:
        type: integer
    end:
      description: The latest creation date for a generated theme to return, represented as milleseconds from epoch time
      in: query
      name: end
      required: false
      schema:
        type: integer
    limit:
      description: Specific number of results to return
      in: query
      name: limit
      required: false
      schema:
        maximum: 1000
        minimum: 1
        type: integer
    Authorization-Bearer:
      description: Bearer YOUR_API_KEY
      in: header
      name: Authorization
      required: true
      schema:
        type: string
    cursor:
      description: A Base64 encoded string representing an opaque cursor position
      in: query
      name: cursor
      required: false
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Use `API-Key YOUR_API_KEY` for v2 endpoints or `Bearer YOUR_API_KEY` for export endpoints.
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true