Get NPS Over Time

Track Net Promoter Score and promoter, passive, and detractor share over time.

get_nps_over_time

Description

Returns the account Net Promoter Score as a time series, including the promoter, passive, and detractor split for each period.

Parameters

Parameter	Type	Required	Default	Description
startDate	string	No	12 months ago when no period is requested	Start date in MM/DD/YYYY format
endDate	string	No	Today when no period is requested	End date in MM/DD/YYYY format
reviewSites	list[integer]	No	All sources	Review source IDs, such as 2 for Google, 1 for Yelp, 110 for Facebook, or 100 for Birdeye

Example Usage

Is our Net Promoter Score improving, and how has the detractor share changed?

Example Response

{
  "totalCount": 120,
  "avgNpsScore": "42",
  "promoters": "62",
  "passives": "18",
  "detractors": "20",
  "dataPoints": [
    {
      "label": "01/01/2026 - 01/31/2026",
      "shortLabel": "Jan 2026",
      "startDate": "01/01/2026",
      "endDate": "01/31/2026",
      "detractorPercentile": 22,
      "passivePercentile": 18,
      "promoterPercentile": 60,
      "npsScore": 38,
      "positiveCount": 36,
      "negativeCount": 13,
      "neutralCount": 11,
      "totalCount": 60
    },
    {
      "label": "02/01/2026 - 02/28/2026",
      "shortLabel": "Feb 2026",
      "startDate": "02/01/2026",
      "endDate": "02/28/2026",
      "detractorPercentile": 18,
      "passivePercentile": 18,
      "promoterPercentile": 64,
      "npsScore": 46,
      "positiveCount": 38,
      "negativeCount": 11,
      "neutralCount": 11,
      "totalCount": 60
    }
  ],
  "groupByType": "month"
}

Response Fields

Field	Description
totalCount	Total responses counted
avgNpsScore	Account NPS
promoters	Promoter percentage
passives	Passive percentage
detractors	Detractor percentage
dataPoints	Period-level NPS, counts, percentages, labels, and dates
groupByType	Time bucket selected by the service

Notes

• NPS ranges from -100 to 100; a negative score is valid.
• promoters, passives, and detractors are percentages, not raw counts — as is the top-level avgNpsScore, which is returned as a string, not a number. Cast before doing arithmetic.
• Use get_nps_by_location for location comparisons.
• When startDate/endDate are both omitted, the live API does not default to 12 months back — it returned the account’s full history (back to 1990 in testing, dateDiff of 13,000+ days) bucketed by year. Pass explicit dates for a bounded trend.