> ## 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 NPS drivers > Company NPS against a product usage metric and ARR. Company scores follow your rollup rules. The response carries a 95% margin of error with every NPS, plus plain and revenue-weighted NPS across the workspace. Archived Companies are left out. A Company with no usage value or no ARR is reported in `missing`, never as zero. Without `metric`, GainTrace uses the first of `events_30d`, `engagement_score`, `dau_wau_ratio` and `seat_utilization` that has data, or else your most-covered metric definition. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `read:surveys` ## OpenAPI ````yaml /openapi.json get /surveys/nps-drivers 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: /surveys/nps-drivers: get: tags: - Surveys summary: Get NPS drivers description: >- Company NPS against a product usage metric and ARR. Company scores follow your rollup rules. The response carries a 95% margin of error with every NPS, plus plain and revenue-weighted NPS across the workspace. Archived Companies are left out. A Company with no usage value or no ARR is reported in `missing`, never as zero. Without `metric`, GainTrace uses the first of `events_30d`, `engagement_score`, `dau_wau_ratio` and `seat_utilization` that has data, or else your most-covered metric definition. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `read:surveys` operationId: getNpsDrivers parameters: - name: metric in: query description: >- The usage metric: `events_30d`, `active_people_30d`, `active_days_30d`, `engagement_score`, `dau_wau_ratio`, `seat_utilization`, `event:` for one product event, or `def:` for a metric definition. Take values from `metrics` in a previous response. A value in the wrong format returns `400`. A well-formed metric your workspace has no data for returns `404`. schema: type: string responses: '200': description: The drivers. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/NpsDrivers' '400': $ref: '#/components/responses/BadRequest' '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: schemas: NpsDrivers: type: object required: - windowDays - method - reportingCurrency - metric - metrics - points - overall - quadrants - missing - truncated properties: windowDays: type: integer description: The rollup window from `GET /surveys/rollup-rules`. method: type: string description: One sentence describing how Company scores were built. reportingCurrency: type: string metric: oneOf: - $ref: '#/components/schemas/UsageMetricOption' - type: 'null' description: >- The usage metric the points use. `null` when the workspace has no usage data. metrics: type: array items: $ref: '#/components/schemas/UsageMetricOption' description: >- Every metric you can send as `metric`. Metrics with no data are not offered. points: type: array description: >- One point per Company with NPS answers in the window, largest ARR first. Capped at 2,000. items: type: object required: - companyId - name - nps - margin - people - usage - arr properties: companyId: type: string format: uuid name: type: string nps: type: integer margin: type: integer description: The 95% margin of error. people: type: integer description: People whose answers count toward this Company's NPS. usage: type: - number - 'null' description: >- The Company's value for the metric. `null` when it has none, never zero. arr: type: - integer - 'null' description: >- ARR in minor units of `reportingCurrency`. `null` when the Company has no ARR or no exchange rate exists. overall: type: object properties: plain: oneOf: - allOf: - $ref: '#/components/schemas/NpsInterval' - type: object properties: people: type: integer - type: 'null' description: NPS across everyone, each Person counted once. revenueWeighted: oneOf: - allOf: - $ref: '#/components/schemas/NpsInterval' - type: object properties: companies: type: integer arr: type: integer description: >- ARR of the Companies in the calculation, in minor units of `reportingCurrency`. - type: 'null' description: >- NPS where each Company counts in proportion to its ARR. Companies without ARR are left out. quadrants: type: array description: Companies split at the median usage and at NPS 0. items: type: object properties: key: type: string enum: - high_usage_positive - high_usage_negative - low_usage_positive - low_usage_negative companies: type: integer arrMinor: type: integer medianUsage: type: - number - 'null' missing: type: object description: What the numbers leave out. properties: usage: type: integer description: Points with no usage value. arr: type: integer description: Points with no ARR. unconvertedCurrencies: type: array items: type: string truncated: type: boolean description: '`true` when there were more than 2,000 points.' UsageMetricOption: type: object required: - key - label - unit - group - window - companies properties: key: type: string description: The value to send as `metric`. label: type: string unit: type: - string - 'null' group: type: string enum: - events - health - metrics window: type: string enum: - before_answer - current - latest_value description: >- How the value is read. `before_answer` covers the 30 days up to the Company's latest answer. `current` is the Company's value now. `latest_value` is the newest recorded value. companies: type: integer description: How many Companies have data for this metric. NpsInterval: type: object required: - nps - margin - low - high - 'n' - method properties: nps: type: integer description: NPS from -100 to 100. margin: type: integer description: The 95% margin of error, in NPS points. low: type: integer high: type: integer 'n': type: number description: The effective sample size. method: type: string enum: - wald - adjusted_wald description: >- `adjusted_wald` is used when every answer falls in one group, so a small sample never reads as a margin of zero. 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: BadRequest: description: The request could not be parsed (for example, malformed JSON). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: Invalid JSON body doc_url: https://docs.gaintrace.com/errors#bad_request 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.