Skip to main content
The /v1/scores endpoint returns a single aggregated, anonymity-protected engagement score for a specified set of questions over a given time window. Use it to track engagement trends in your warehouse without exposing individual responses. The score is aggregated over every response to the requested question_ids within the period_from / period_to window. When the response base is below the anonymity threshold, the score is suppressed (score: null, suppressed: true) so you can distinguish “hidden for privacy” from “no data”. The threshold is configured per survey; when the requested questions span multiple surveys, the strictest threshold applies. All requested questions must be of the same kind — either all eNPS questions or all non-eNPS questions. Mixing eNPS and non-eNPS questions in one request returns a 400 error. The unit field tells you which kind was aggregated.

​
Endpoint

​
Query Parameters

​
string
required
Comma-separated question IDs to aggregate into a single score, for example 121,122. These are the same integer IDs returned by the /v1/questions endpoint.
​
string
required
RFC 3339 datetime. Only aggregate responses given at or after this date.
​
string
required
RFC 3339 datetime. Only aggregate responses given at or before this date.

​
Example Request

​
Example Response

When the response base is below the anonymity threshold, the score is suppressed:

​
Response Fields

​
number | null
The aggregated score. Its range depends on unit: 0–100 for favorability_percent, -100–100 for enps. null when suppressed is true.
​
string
The unit of the score value. favorability_percent (0–100) for non-eNPS questions — each question is normalized to 0–100 and the results are averaged; enps (-100–100) when all requested questions are eNPS questions.
​
integer
Number of unique respondents the score is based on.
​
boolean
Indicates the score was hidden because the response base is below the account anonymity threshold.
​
string | null
Reason the score was suppressed. Currently below_anonymity_threshold. null when suppressed is false.
Scores are anonymity-protected. When the response base is below the per-survey anonymity threshold, score is null, suppressed is true, and suppression_reason explains why — rather than returning an error.
URL-encode datetime parameters in GET requests. The + sign in timezone offsets must be encoded as %2B. See Error Handling if you encounter 400 errors.