Survey Analytics

Get aggregated analytics and NPS data for a survey.

Endpoint

GET /v1/surveys/{id}/analytics

Path Parameters

Parameter	Type	Description
id	integer	Survey ID

Authentication

Requires an API key with the surveys:read scope.

Query Parameters

Parameter	Type	Description
date_from	string	Filter from date (YYYY-MM-DD)
date_to	string	Filter to date (YYYY-MM-DD)

Response

Success (200 OK)

{
  "data": {
    "survey_id": 1,
    "survey_name": "Customer Satisfaction Survey",
    "total_responses": 156,
    "nps": {
      "score": 42,
      "total_responses": 156,
      "promoters": 89,
      "passives": 45,
      "detractors": 22,
      "promoter_percentage": 57.1,
      "passive_percentage": 28.8,
      "detractor_percentage": 14.1
    },
    "date_range": {
      "from": "2026-01-01",
      "to": "2026-01-31"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-15T12:00:00+00:00"
  }
}

Response Fields

Analytics Object

Field	Type	Description
survey_id	integer	Survey ID
survey_name	string	Survey name
total_responses	integer	Total number of responses in date range
nps	object	NPS analytics (null if survey has no NPS field)
date_range	object	Applied date filters

NPS Object

Field	Type	Description
score	integer	NPS score (-100 to +100)
total_responses	integer	Responses with NPS rating
promoters	integer	Count of promoters (9-10)
passives	integer	Count of passives (7-8)
detractors	integer	Count of detractors (0-6)
promoter_percentage	number	Percentage of promoters
passive_percentage	number	Percentage of passives
detractor_percentage	number	Percentage of detractors

Understanding NPS Score

The Net Promoter Score is calculated as:

NPS = % Promoters - % Detractors

NPS Range	Interpretation
70+	Excellent
50-69	Great
30-49	Good
0-29	Needs improvement
Below 0	Critical

Example: Monthly NPS Tracking

Track NPS over time by querying different date ranges:

# January 2026
curl "https://app.equipdash.com/api/v1/surveys/1/analytics?date_from=2026-01-01&date_to=2026-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

# February 2026
curl "https://app.equipdash.com/api/v1/surveys/1/analytics?date_from=2026-02-01&date_to=2026-02-28" \
  -H "Authorization: Bearer YOUR_API_KEY"

Survey Without NPS Field

If the survey doesn't contain an NPS rating field, the nps object will be null:

{
  "data": {
    "survey_id": 2,
    "survey_name": "Equipment Feedback",
    "total_responses": 45,
    "nps": null,
    "date_range": {
      "from": null,
      "to": null
    }
  }
}

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks surveys:read scope
403	forbidden	Survey belongs to another supplier
404	not_found	Survey not found

Example Request

curl -X GET "https://app.equipdash.com/api/v1/surveys/1/analytics?date_from=2026-01-01&date_to=2026-01-31" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..."

Use Cases

Building an NPS Dashboard

Fetch analytics for all surveys and display in a dashboard:

const surveys = await fetch('/api/v1/surveys', { headers });
const analytics = await Promise.all(
  surveys.data.map(survey =>
    fetch(`/api/v1/surveys/${survey.id}/analytics`, { headers })
  )
);

// Display NPS scores for each survey
analytics.forEach((data, i) => {
  console.log(`${surveys.data[i].name}: NPS ${data.nps?.score ?? 'N/A'}`);
});

Identifying At-Risk Customers

Use the responses endpoint with NPS filtering to find detractors:

curl "https://app.equipdash.com/api/v1/surveys/1/responses?nps_category=detractor" \
  -H "Authorization: Bearer YOUR_API_KEY"

Then follow up with these customers to address their concerns.