> ## Documentation Index > Fetch the complete documentation index at: https://docs.gaintrace.com/llms.txt > Use this file to discover all available pages before exploring further. # List survey responses > List responses from every GainTrace survey (NPS, CSAT, CES and custom), newest first, across the email, in-app and API channels, plus older answers collected before public links, QR codes and kiosks were removed. Responses imported through the NPS import endpoint are not included. Filters combine with AND. An unknown query parameter returns `422`. Pagination is `limit` and `offset`; there is no cursor. `from` and `to` are inclusive and compare against `submittedAt`. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `read:surveys` ## OpenAPI ````yaml /openapi.json get /survey-responses openapi: 3.1.0 info: title: GainTrace API version: 1.0.0 description: >- The GainTrace REST API (v1). Read your customer data and push product-usage events, metric events, and signals into GainTrace. All endpoints are authenticated with a Bearer API key and scoped to a single workspace. Each API key can send 60 requests a minute. A `429` response includes a `Retry-After` header with the seconds to wait. servers: - url: https://app.gaintrace.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Companies description: Read and manage canonical company records. - name: Signals description: Read, create, and manage buyer / risk signals. - name: Ingest description: Push product-usage and metric events into GainTrace. - name: Contacts description: >- The original path for People. It shares its handlers with /people, and also offers delete-by-key. - name: Webhooks description: Subscribe to workspace events with signed, retried delivery. - name: People description: Read and manage People. One Person can belong to many Companies. - name: NPS responses description: Import NPS scores from another survey tool and read your NPS history. - name: Surveys description: >- Create and launch surveys, request invitations, record responses and mint in-app sessions. - name: Survey responses description: Read the responses collected by your surveys. - name: Survey segments description: Save groups of Companies and People that surveys can target. - name: Survey imports description: Pull responses from the survey tools your workspace has connected. paths: /survey-responses: get: tags: - Survey responses summary: List survey responses description: >- List responses from every GainTrace survey (NPS, CSAT, CES and custom), newest first, across the email, in-app and API channels, plus older answers collected before public links, QR codes and kiosks were removed. Responses imported through the NPS import endpoint are not included. Filters combine with AND. An unknown query parameter returns `422`. Pagination is `limit` and `offset`; there is no cursor. `from` and `to` are inclusive and compare against `submittedAt`. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `read:surveys` operationId: listSurveyResponses parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - name: surveyId in: query description: Only responses to this survey. schema: type: string format: uuid - name: companyId in: query description: Only responses attributed to this company. schema: type: string format: uuid - name: measure in: query description: Only responses to surveys of this measure. schema: $ref: '#/components/schemas/SurveyMeasure' - name: band in: query description: Only responses in this score band. schema: type: string enum: - positive - neutral - negative - unscored - name: status in: query description: >- Review status. `open` means any status except `resolved`. `overdue` means open past the workspace hours-to-close rule (`GET /surveys/case-rules`). schema: type: string enum: - new - in_progress - resolved - open - overdue - name: from in: query description: >- Submitted at or after this time. Use an ISO 8601 timestamp with an offset, for example `2026-10-01T00:00:00Z`. schema: type: string format: date-time - name: to in: query description: Submitted at or before this time. Same format as `from`. schema: type: string format: date-time - name: theme in: query description: Only responses whose written answers mention this theme. schema: type: string enum: - onboarding - reliability - performance - usability - missing_functionality - integrations - support_quality - documentation - pricing_value - billing_admin - security_compliance - account_management - reporting_analytics - mobile - name: subjectType in: query description: Only responses about this kind of record. schema: type: string enum: - deal - ticket - plan - record - name: subjectId in: query description: >- Only responses about this one record. Send it with `subjectType`; without it the call returns `422`. schema: type: string format: uuid responses: '200': description: A page of responses. content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/SurveyResponse' meta: $ref: '#/components/schemas/Meta' example: data: - id: 0d5e8a9b-1c2d-4e3f-8a4b-5c6d7e8f9a0b surveyId: 7b6f2c1e-4d3a-4b5c-9e8f-1a2b3c4d5e6f surveyName: Relationship NPS measure: nps score: 4 scaleMax: 10 band: negative comment: Reports take too long to load. answers: q0: 4 q1: Reports take too long to load. questionAnswers: - key: q0 number: 1 text: How likely are you to recommend us to a colleague? type: rating value: 4 display: '4' - key: q1 number: 2 text: What is the main reason for your score? type: text value: Reports take too long to load. display: Reports take too long to load. companyId: a1f0c2d3-5e6f-4a7b-8c9d-0e1f2a3b4c5d personId: c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f subject: type: ticket id: 5d1e7a3b-2c4f-4b6a-8d9e-0f1a2b3c4d5e respondentEmail: ana@acme.com respondentName: Ana Ruiz status: new ownerId: null taskId: null submittedAt: '2026-10-14T09:12:43.000Z' reviewedAt: null meta: limit: 50 offset: 0 count: 1 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' components: parameters: limit: name: limit in: query description: Max rows to return. Default 50, max 100. schema: type: integer default: 50 maximum: 100 minimum: 1 offset: name: offset in: query description: Rows to skip (pagination). schema: type: integer default: 0 minimum: 0 schemas: SurveyMeasure: type: string enum: - nps - csat - ces - custom description: >- `nps` is a 0-10 scale. `csat` and `ces` use a 1-5 or 1-7 scale. `custom` has no band and its responses are `unscored`. For `nps`, `csat` and `ces`, the first question must be a required `rating` or `scale` question: it carries the score. SurveyResponse: type: object required: - id - surveyId - surveyName - measure - score - scaleMax - band - comment - answers - questionAnswers - subject - status - submittedAt description: >- The same shape as the `survey_response` webhook payload for a GainTrace survey, without `source` and `channel`. properties: id: type: string format: uuid surveyId: type: string format: uuid surveyName: type: string measure: $ref: '#/components/schemas/SurveyMeasure' score: type: integer nullable: true scaleMax: type: integer nullable: true description: The maximum of the survey's first-question scale. band: type: string enum: - positive - neutral - negative - unscored description: >- NPS: 9-10 positive, 7-8 neutral, 0-6 negative. CSAT and CES: the top two points of the scale are positive, the bottom half is negative, the rest neutral. Custom surveys and answers without a score are `unscored`. comment: type: string nullable: true answers: type: object additionalProperties: true description: >- Answers keyed `q0`, `q1` and so on, plus `comment` and `hidden` when present. When the AI follow-up was asked, `_probe` holds its `question` and the respondent's `answer`. Use `questionAnswers` to read answers with their question text. questionAnswers: type: array items: $ref: '#/components/schemas/SurveyQuestionAnswer' description: Each answer with its question text, in question order. companyId: type: string format: uuid nullable: true personId: type: string format: uuid nullable: true subject: oneOf: - $ref: '#/components/schemas/SurveySubject' - type: 'null' description: >- The deal, ticket, plan or custom record the response is about. `null` when it isn't linked to one, and always `null` on anonymous surveys. respondentEmail: type: string nullable: true respondentName: type: string nullable: true status: type: string enum: - new - in_progress - resolved ownerId: type: string format: uuid nullable: true taskId: type: string format: uuid nullable: true submittedAt: type: string format: date-time reviewedAt: type: string format: date-time nullable: true language: type: string description: >- The language code the respondent answered in, such as `en` or `pt-BR`. Meta: type: object properties: limit: type: integer offset: type: integer count: type: integer description: Number of rows in this page. SurveyQuestionAnswer: type: object required: - key - number - text - type - value - display description: >- One answer paired with its question wording. Statements and unanswered questions are left out. properties: key: type: string description: '`q0`, `q1` and so on, the same key as in `answers`.' number: type: integer description: The question number, starting at 1. text: type: string description: The question text. type: type: string enum: - rating - scale - text - multiple_choice - multi_select - dropdown - matrix - ranking - date - statement - consent value: description: >- The stored answer: a number for a score, a string for text, a choice, or a `YYYY-MM-DD` date, a list of strings for checkboxes and rankings (in rank order), an object of row to column for a matrix, and `true` for consent. display: type: string description: The answer as readable text, for example `Reporting, Alerts`. SurveySubject: type: object required: - type - id description: The record the response is about. properties: type: type: string enum: - deal - ticket - plan - record id: type: string format: uuid description: The GainTrace record id. Error: type: object required: - error description: The standard error envelope. Every 4xx/5xx response uses this shape. properties: error: type: object required: - code - message properties: code: type: string enum: - bad_request - unauthorized - payment_required - forbidden - not_found - conflict - unprocessable_entity - rate_limit_exceeded - internal_server_error - service_unavailable - gateway_timeout description: >- Stable, machine-readable error code. Each code maps to exactly one HTTP status. message: type: string description: >- Human-readable, safe description of what went wrong. Never contains internal or provider detail. doc_url: type: string format: uri example: https://docs.gaintrace.com/errors#not_found description: Deep link to this code in the Errors reference. responses: Unauthorized: description: Missing, malformed, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Missing Authorization header doc_url: https://docs.gaintrace.com/errors#unauthorized Forbidden: description: >- The key is valid but lacks the required scope, the origin is not allowed, or API v1 is not enabled for the workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: 'Insufficient scope: write:companies required' doc_url: https://docs.gaintrace.com/errors#forbidden UnprocessableEntity: description: The request was well-formed but a value failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unprocessable_entity message: 'Request validation failed. name: name is required' doc_url: https://docs.gaintrace.com/errors#unprocessable_entity RateLimited: description: >- The per-key rate limit was exceeded. Each API key can send 60 requests per minute, counted in calendar-minute windows. The `Retry-After` header gives the whole seconds (1 to 60) until the next window opens. Wait that long, then retry. headers: Retry-After: description: Whole seconds until the next one-minute window starts. schema: type: integer minimum: 1 maximum: 60 example: 23 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: >- Can't accept more than 60 requests a minute from one API key. Retry in 23 seconds. doc_url: https://docs.gaintrace.com/errors#rate_limit_exceeded InternalServerError: description: >- An unexpected error occurred on our side. The failure is logged; retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_server_error message: Something went wrong. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#internal_server_error ServiceUnavailable: description: >- A backing service (for example, the database) was temporarily unavailable. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: service_unavailable message: We had trouble reaching the database. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#service_unavailable GatewayTimeout: description: >- The request took too long upstream before completing. Retry, and reduce batch size for large payloads. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: gateway_timeout message: The request timed out. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#gateway_timeout securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer API key. Secret server keys start with `gt_live_`; client-safe browser keys start with `gt_pub_` (write-only, origin-pinned). Create and scope keys in Settings → API Keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.