Analytics

Retrieve comprehensive analytics for a survey.

Example Request

curl -X GET "https://app.surventrics.ai/api/v1/surveys/SURVEY_ID/analytics" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "surveyId": "550e8400-e29b-41d4-a716-446655440000",
  "responseStats": {
    "total": 250,
    "completed": 198,
    "abandoned": 42,
    "inProgress": 10,
    "completionRate": 79.2,
    "responseCount": 196,
    "viaAgents": 3
  },
  "timing": {
    "averageCompletionSeconds": 245,
    "medianCompletionSeconds": null
  },
  "questions": [
    {
      "questionId": "q_001",
      "questionTitle": "How satisfied are you with our service?",
      "questionType": "single_choice",
      "responseCount": 195,
      "skipRate": 1.5,
      "skippedOfShown": { "skipped": 3, "shown": 198 },
      "skipRateOfShown": 1.5,
      "skipsAvailability": "available"
    },
    {
      "questionId": "q_002",
      "questionTitle": "How likely are you to recommend us?",
      "questionType": "nps",
      "responseCount": 198,
      "skipRate": 0.0,
      "skippedOfShown": null,
      "skipRateOfShown": null,
      "skipsAvailability": "not_skippable"
    }
  ],
  "daily": [
    { "date": "2024-01-15", "responses": 12, "completions": 10 },
    { "date": "2024-01-16", "responses": 25, "completions": 22 },
    { "date": "2024-01-17", "responses": 18, "completions": 15 }
  ],
  "generatedAt": "2024-01-21T09:00:00Z"
}

Response Fields

responseStats

timing

questions

Array of per-question statistics:

daily

Daily response counts for the last 30 days:

devices and geography

With include=devices or include=geography: sessions by device type or by country.

Banner tables

Read a survey's banners (saved sets of breaks) and run them: every question against the same columns, with significance letters. Banners are built in the app; the API reads and runs them. Requires the bannerTables feature, on the Business plan and above.

The survey's banners, each with its columns resolved (group, label, letter) and any group that no longer fits. Runs nothing and takes no query.

A run's contents: the base, the weighting used, the columns, and one line per table with its Total base. No cells; fetch a table for those. Computes every table, so it spends your organisation's contents allowance (30 an hour), its own: browsing a run never spends a tab book.

One table: bases per column, and per row the count, proportion, mean where relevant and the letters of the columns it is significantly higher than. :tableKey is a question id, or questionId~rowId for one statement of a grid.

The run as an Excel workbook (Contents, Banner and Tables sheets). Spends your organisation's tab book allowance (30 an hour), shared with the in-app download and separate from the contents allowance.

Example Request

curl -X GET "https://app.surventrics.ai/api/v1/surveys/SURVEY_ID/banners/BANNER_ID/tables?confidence=90&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

The last three endpoints. The query is strict: an unrecognised value, a parameter given twice, or from after to is a 400 listing every bad parameter in details.invalid.

Reading the response

Every label comes with a code beside it. A group carries source (question or attribute) and questionId or attribute; a column its own key; a label the product words carries labelKey and labelParams. In a run (the contents call and one table) the Total column is always first, with the id total and no letter; the banner list returns the breaks' columns only, without Total. Letters name columns in the same group that the figure is significantly higher than (pairwise, uncorrected). A column with fewer than 5 respondents is marked lowBase and never tested.

Refusals

A run is refused before anything is computed, as { error: { code, message, details: { reason } } }. Reasons are codes, never sentences. A refused run is not counted against an allowance.

Also 401, 403 (scope, plan or feature) and 404 (a survey, banner or table key that is not there), as on every endpoint.

Use Cases

Monitoring Dashboard

Poll the analytics endpoint to display real-time metrics on your dashboard:

// JavaScript example
async function refreshMetrics(surveyId) {
  const response = await fetch(
    `https://app.surventrics.ai/api/v1/surveys/${surveyId}/analytics`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );

  const data = await response.json();

  console.log(`Completion rate: ${data.responseStats.completionRate}%`);
  console.log(`Total responses: ${data.responseStats.total}`);
  console.log(`Avg completion: ${Math.round(data.timing.averageCompletionSeconds / 60)} min`);
}

Identifying Problem Questions

Find questions with high skip rates that may need improvement:

// Find questions people skip: shown, left blank and moved past, > 10%
const problemQuestions = data.questions
  .filter(q => q.skipsAvailability === "available" && q.skipRateOfShown > 10)
  .sort((a, b) => b.skipRateOfShown - a.skipRateOfShown);

console.log('Questions needing attention:', problemQuestions);

Trend Analysis

Use the daily data to visualize response trends:

// Calculate 7-day average
const recentDays = data.daily.slice(-7);
const avgDaily = recentDays.reduce((sum, d) => sum + d.completions, 0) / 7;

console.log(`7-day avg: ${avgDaily.toFixed(1)} completions/day`);