> ## 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. # Get a survey response > Read one GainTrace survey response, with its answers, the questions they answer, and the record it is about. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `read:surveys` ## OpenAPI ````yaml /openapi.json get /survey-responses/{id} 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/{id}: get: tags: - Survey responses summary: Get a survey response description: >- Read one GainTrace survey response, with its answers, the questions they answer, and the record it is about. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `read:surveys` operationId: getSurveyResponse parameters: - $ref: '#/components/parameters/surveyResponseId' responses: '200': description: The response. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SurveyResponse' 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 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' components: parameters: surveyResponseId: name: id in: path required: true description: The survey response's UUID. schema: type: string format: uuid schemas: 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`. 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. 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 NotFound: description: >- The resource, or a resource you referenced, was not found in this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Company not found doc_url: https://docs.gaintrace.com/errors#not_found 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.