Flashpoint.AIFlashpoint.AIdocs

Analyze

Every response lands in the same store regardless of how it was collected. The API surfaces summary dashboards, per-question frequencies, crosstabs, NPS, statistical tests, AI takeaways, and individual response management.

Summary dashboard

curl https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Response:

{
  "total_responses": 247,
  "complete": 210,
  "incomplete": 30,
  "screen_out": 7,
  "completion_rate": 85.0,
  "median_time_seconds": 312,
  "daily_timeline": [
    {"date": "2026-05-20", "count": 42},
    {"date": "2026-05-21", "count": 58},
    {"date": "2026-05-22", "count": 67}
  ],
  "country_breakdown": [
    {"country": "US", "count": 180},
    {"country": "GB", "count": 35},
    {"country": "CA", "count": 32}
  ]
}

Filter by survey version or panel:

# Only Prolific responses
curl "...?panel_id={prolific_panel_id}"

# Only public-link traffic
curl "...?panel_id=open"

Via the agent

"How are results coming for my NPS survey?"

The agent calls get_analytics and summarizes the headline metrics.

Frequencies

Answer distribution for every question, or for a single question.

All questions

curl https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/frequencies \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Response (array of frequency objects):

[
  {
    "question_id": "Q1",
    "label": "Q1",
    "text": "What is your age group?",
    "type": "select",
    "total_responses": 210,
    "distribution": [
      {"value": "18-24", "count": 42, "percentage": 20.0},
      {"value": "25-34", "count": 68, "percentage": 32.4},
      {"value": "35-44", "count": 55, "percentage": 26.2},
      {"value": "45+",   "count": 45, "percentage": 21.4}
    ]
  }
]

Single question

curl https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/frequencies/Q1 \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Via the agent

"Show me the breakdown for Q1"

The agent calls get_frequencies with question_label="Q1".

Crosstabs

Two-dimensional cross-tabulation with chi-square, Cramer's V, and adjusted standardized residuals. Supports 2-way and 3-way (banner variable) analysis.

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/crosstab \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "rowVariable": {"questionLabel": "Q4"},
    "colVariable": {"questionLabel": "Q1"}
  }'

Response:

{
  "status": "success",
  "tables": {
    "Total": {
      "rows": [
        {
          "value": "Very satisfied",
          "18-24": {"count": 15, "rowPct": 35.7, "colPct": 22.1},
          "25-34": {"count": 22, "rowPct": 52.4, "colPct": 32.4},
          "total": {"count": 42}
        }
      ],
      "statistics": {
        "chiSquare": 12.45,
        "pValue": 0.0142,
        "cramersV": 0.24,
        "sampleSize": 210
      }
    }
  }
}

3-way crosstab (banner variable)

Add a bannerVariable to segment the table:

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/crosstab \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "rowVariable": {"questionLabel": "Q4"},
    "colVariable": {"questionLabel": "Q1"},
    "bannerVariable": {"questionLabel": "Q2"}
  }'

Returns one table per banner category plus a "Total" table.

Available crosstab questions

curl https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/crosstab/questions \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Returns all questions eligible as crosstab variables. Free-text, conjoint, and van-westendorp questions are excluded since they do not produce categorical buckets.

Via the agent

"Crosstab satisfaction by age group"

The agent calls get_crosstab with row_label="Q4" and column_label="Q1".

NPS

Net Promoter Score for NPS-type questions.

curl https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/nps/Q3 \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Response:

{
  "question_id": "Q3",
  "nps_score": 32.5,
  "total": 210,
  "promoters": 95,
  "promoter_pct": 45.2,
  "passives": 63,
  "passive_pct": 30.0,
  "detractors": 52,
  "detractor_pct": 24.8
}

NPS = % Promoters (9-10) minus % Detractors (0-6). Range: -100 to +100.

BucketScore range
Promoter9-10
Passive7-8
Detractor0-6

Via the agent

"What's our NPS?"

The agent calls get_nps with the NPS question label from the survey.

Statistical testing

Chi-square test of independence on any two categorical variables.

Via the agent

"Is the difference in brand preference between males and females statistically significant?"

The agent calls stat_test with the two question labels. Response:

{
  "test": "chi_square_independence",
  "row_question": "Q2",
  "column_question": "Q5",
  "chi_square": 18.3421,
  "p_value": 0.002614,
  "degrees_of_freedom": 6,
  "interpretation": "Highly significant -- strong evidence of association (p < 0.01)",
  "sample_size": 210,
  "segment_filter": null
}

Interpretation thresholds:

p-valueInterpretation
< 0.01Highly significant — strong evidence of association
< 0.05Statistically significant at 95% confidence
< 0.10Marginally significant — suggestive but not conclusive
>= 0.10Not statistically significant

Segment filtering

Slice any analytics query to a subgroup using the DSL filter syntax — the same expression language used for skip logic.

Examples

Q1 == `1`              -- only respondents who picked option 1 on Q1
Q2 IN [`1`,`2`]        -- Q2 is option 1 or 2
Q7 > 50               -- numeric Q7 greater than 50

Pass the filter as a query parameter (REST) or segment_filter argument (agent tools).

Via the agent

"Show me NPS for respondents aged 25-34"

The agent adds segment_filter="Q1 == '2'" (assuming Q1 option 2 is the 25-34 age band) to the get_nps call.

Response management

List responses

curl "https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/responses?status=complete&limit=50&offset=0" \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Response:

{
  "total": 210,
  "responses": [
    {
      "id": "resp_...",
      "survey_id": "srv_...",
      "status": "COMPLETE",
      "country": "US",
      "started_at": "2026-05-20T10:00:00Z",
      "completed_at": "2026-05-20T10:05:12Z",
      "time_elapsed_ms": 312000,
      "is_preview": false,
      "excluded": false
    }
  ]
}

Get response detail

curl https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/responses/{response_id} \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Returns the full answer data, geo, panel info, fraud signals, and exclusion status.

Exclude a response

curl -X PATCH https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/responses/{response_id} \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "excluded": true,
    "reason": "Suspected bot -- completed in 8 seconds"
  }'

Excluded responses remain in the database (re-include by setting excluded: false) but are removed from all analytics views by default.

Bulk exclusion

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/responses/bulk \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "exclude",
    "response_ids": ["resp_abc", "resp_def", "resp_ghi"],
    "reason": "Straightlining detected"
  }'

The action field accepts exclude or include.

Via the agent

"Exclude that response — it's a bot"

The agent calls exclude_response with excluded=true and the reason you provide.

Reports

Structured JSON report

curl "https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/report?include_takeaways=true" \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Returns a composite document with summary, per-question frequencies, and (optionally) AI key takeaways in one payload.

{
  "survey": {
    "id": "srv_...",
    "title": "Customer Satisfaction Q2",
    "status": "active",
    "version": 3
  },
  "generated_at": "2026-05-26T14:00:00Z",
  "summary": { "...summary dashboard fields..." },
  "questions": [ "...frequency objects per question..." ],
  "key_takeaways": { "...AI takeaways (if requested)..." }
}

PDF report download

curl -o report.pdf \
  "https://surveys.flashpoint.ai/api/v1/surveys/{survey_id}/analytics/report/download" \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Returns application/pdf with quota disposition and overall metrics.

Exports

The agent can export survey data in multiple formats:

FormatToolContent
CSVexport_csvResponse data — one row per respondent
DOCXexport_docxSurvey instrument — questions, options, logic
PDFexport_pdfSurvey instrument — polished, non-editable

Each export uploads to S3 and returns a presigned download URL valid for 1 hour.

Via the agent

"Export the responses as CSV"

"Give me a Word doc of the survey instrument"

Next steps