AI insights

Flashpoint.AI analyzes survey data directly — theme extraction from open-ended responses, executive summaries with evidence, survey quality scoring, and web research to ground survey design in real-world context.

Open-end analysis

The analyze_open_ends tool reads free-text responses for a single question and returns themes, sentiment, notable quotes, and actionable insights.

Via the agent

"Analyze the open-ended responses for Q5"

The agent calls analyze_open_ends with the question label. It fetches up to 100 completed, non-excluded text responses (configurable up to 500) and sends them to Flashpoint.AI's AI for qualitative analysis.

Response shape

{
  "total_analyzed": 87,
  "themes": [
    {
      "theme": "Delivery speed",
      "count": 34,
      "percentage": 39.1,
      "example": "The package arrived two days early, which was great"
    },
    {
      "theme": "Packaging quality",
      "count": 22,
      "percentage": 25.3,
      "example": "Box was damaged when it arrived"
    }
  ],
  "sentiment": {
    "positive": 48.3,
    "negative": 31.0,
    "neutral": 20.7
  },
  "notable_quotes": [
    {
      "text": "Best customer service I've experienced in years",
      "theme": "Customer service"
    },
    {
      "text": "Had to call three times before anyone helped",
      "theme": "Customer service"
    }
  ],
  "insights": [
    {
      "finding": "Delivery speed is the top driver of positive sentiment",
      "implication": "Investing in faster shipping may improve overall satisfaction scores"
    },
    {
      "finding": "Packaging complaints correlate with repeat-purchase hesitancy",
      "implication": "Packaging improvements could reduce churn in the 25-34 segment"
    }
  ]
}

Parameters

Parameter	Default	Description
`question_label`	(required)	Label of the open-ended question (e.g. `Q9`)
`max_responses`	100	Maximum responses to analyze (1-500)

Only works on text-type questions. The tool filters to COMPLETE responses that are not excluded or previews.

Results summary

The summarize_results tool generates an executive summary of the entire survey — structured topic clusters with evidence, suitable for a dashboard "AI Insights" panel.

Via the agent

"Give me the key takeaways from this survey"

"Summarize what we learned"

REST endpoint

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

Response shape

{
  "keyPoints": [
    "NPS is driven by delivery speed, not product quality",
    "The 35-44 segment is the most price-sensitive",
    "Awareness is high (87%) but trial is low (12%)"
  ],
  "overallSummary": "The survey reveals strong brand awareness across all segments but a significant gap between awareness and trial. Delivery speed emerges as the primary driver of satisfaction, while pricing concerns are concentrated in the 35-44 age band. Open-ended feedback highlights packaging as an underappreciated pain point.",
  "topics": [
    {
      "topic": "Delivery Experience",
      "summary": "Fast delivery is the strongest predictor of promoter status",
      "positiveCount": 95,
      "negativeCount": 23,
      "evidence": [
        {
          "type": "stat",
          "text": "72% of promoters cite delivery speed as top factor",
          "sentiment": "positive"
        },
        {
          "type": "quote",
          "text": "Arrived two days early -- will order again",
          "sentiment": "positive"
        },
        {
          "type": "stat",
          "text": "Late delivery mentioned in 61% of detractor open-ends",
          "sentiment": "negative"
        }
      ]
    }
  ]
}

Field reference

Field	Type	Description
`keyPoints`	`string[]`	Exactly 3 short bullet points (max 15 words each)
`overallSummary`	`string`	3-4 sentence paragraph
`topics`	`object[]`	4-6 topic clusters
`topics[].topic`	`string`	Short topic name (2-4 words)
`topics[].summary`	`string`	One-sentence summary
`topics[].positiveCount`	`int`	Count of positive signals (0 for neutral topics)
`topics[].negativeCount`	`int`	Count of negative signals (0 for neutral topics)
`topics[].evidence`	`object[]`	2-4 evidence items
`topics[].evidence[].type`	`string`	`stat` or `quote`
`topics[].evidence[].text`	`string`	Evidence text (under 100 chars)
`topics[].evidence[].sentiment`	`string`	`positive`, `negative`, or `neutral`

The endpoint returns {"error": true, "message": "..."} with empty arrays when there are no responses or the AI service is unavailable.

Survey optimization

The optimize_survey tool performs an AI quality review before publishing. It checks for methodological issues and returns a score with specific, actionable suggestions.

Via the agent

"Review my survey for quality issues"

"Is this survey ready to publish?"

Response shape

{
  "score": 78,
  "estimated_minutes": 6.5,
  "issues": [
    {
      "severity": "high",
      "question": "Q4",
      "type": "bias",
      "description": "Leading question -- 'Don't you agree that...' pushes respondents toward agreement"
    },
    {
      "severity": "medium",
      "question": "Q7",
      "type": "cognitive_load",
      "description": "Grid has 12 rows and 7 columns -- respondents will fatigue before row 8"
    },
    {
      "severity": "low",
      "question": null,
      "type": "missing_type",
      "description": "No open-ended question -- consider adding one for qualitative depth"
    }
  ],
  "suggestions": [
    {
      "question": "Q4",
      "action": "Rephrase to neutral wording: 'To what extent do you agree or disagree that...'",
      "rationale": "Neutral framing avoids acquiescence bias and produces more valid data"
    },
    {
      "question": "Q7",
      "action": "Split into two grids of 6 rows each",
      "rationale": "Shorter grids reduce straightlining and improve data quality"
    }
  ]
}

Issue types

Type	What it catches
`bias`	Leading, loaded, or suggestive question wording
`clarity`	Ambiguous or double-barreled questions
`ordering`	Question sequence issues (e.g. priming effects)
`cognitive_load`	Too many options, overly complex grids
`missing_type`	No screener, no open-ended, no demographics
`logic_gap`	Skip logic that leaves dead paths

Research tools

Three tools gather real-world context before or during survey design. They use web search to return synthesized answers with citations.

research_market

Research a market, industry, or topic.

"What are the customer satisfaction drivers for specialty coffee shops?"

research_audience

Research a target audience's demographics, psychographics, and behavior patterns.

"What defines Gen Z sneaker buyers in terms of purchase drivers?"

research_competitors

Research competitors in an industry or product category.

"Who are the main competitors in the US home insurance market and how are they positioned?"

Response shape (all three tools)

{
  "available": true,
  "query": "Customer satisfaction drivers for specialty coffee shops",
  "provider": "perplexity",
  "answer": "The primary drivers of customer satisfaction in specialty coffee are...",
  "citations": [
    {
      "title": "2025 Specialty Coffee Consumer Report",
      "url": "https://example.com/report",
      "snippet": "Quality of beans and brewing consistency ranked highest..."
    }
  ]
}

When the research service is not configured, the tool returns {"available": false} and the agent falls back to its built-in knowledge.

Persisting research sources

After building a survey from research, the agent calls attach_research_sources to store citations on the survey. These persist in survey.settings.research_sources and are visible on the survey overview.

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

The settings.research_sources array in the response contains the stored citations.

Typical research flow

research_audience — understand who you are surveying
research_market — understand the domain context
Plan and create the survey
attach_research_sources — persist the citations on the survey

Next steps

Core analytics and exports: Analyze.
Clean up bad data: Data quality.
Distribute the survey: Distribute.