Pre-Test PredictionsStarter+

Predict phrasing effects before collecting responses. Compare two versions of a question to understand how wording changes may impact response quality and bias.

POST/surveys/:id/pretest/compare

Compare two phrasings of a survey question and receive a prediction about whether the difference in wording is likely to produce meaningfully different response distributions.

Required scope:surveys:read

Plan:Starter+or higher

Rate limit:10/minute per org

Path Parameters

Name	Type	Description
`id`	string	Survey ID (UUID)

Request Body

Name	Type	Description
`phrasingA`	string	First question phrasing (required, max 2000 chars)
`phrasingB`	string	Second question phrasing (required, max 2000 chars)
`category`	string	Pre-test category (required). See category values below.
`audience`	string	Optional free-text description of the target audience (max 500 chars) for additional model context.

Category Values

The category describes which aspect of the two phrasings differs, which gives the model domain context for the prediction.

Value	Description
`question_wording`	Differences in the wording or phrasing of the question
`scale_labeling`	Differences in the response-scale labels or anchors
`question_order`	Differences in the ordering of questions or items
`response_options`	Differences in the answer options offered
`survey_length`	Differences related to overall survey length
`tone_formality`	Differences in tone or formality of the language
`other`	Any other difference between the two phrasings

Example Request

curl -X POST "https://surventrics.ai/api/v1/surveys/SURVEY_ID/pretest/compare" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrasingA": "How satisfied are you with our service?",
    "phrasingB": "How would you rate your experience with our service?",
    "category": "question_wording",
    "audience": "Recent customers (last 30 days)"
  }'

Response

{
  "predictedEffect": 1.4,
  "confidenceInterval": {
    "lower": 0.2,
    "upper": 3.1
  },
  "recommendation": "likely_insignificant",
  "reasoning": "Both phrasings target the same construct (service evaluation) using similar scales. The shift from 'satisfied' to 'rate your experience' is unlikely to produce a meaningfully different response distribution.",
  "category": "question_wording",
  "model": "claude-sonnet-4-6",
  "latencyMs": 1820
}

Response Fields

Name	Type	Description
`predictedEffect`	number	Predicted absolute effect of switching phrasings, in percentage points.
`confidenceInterval`	object	95% confidence interval for the predicted effect: { lower, upper } (percentage points).
`recommendation`	string	Prediction result (see values below)
`reasoning`	string	Short (2-3 sentence) model explanation of the prediction.
`category`	string	The category that was supplied in the request.
`model`	string	Identifier of the model that produced the prediction.
`latencyMs`	number	Server-side prediction latency in milliseconds.

Recommendation Values

Value	Meaning
`likely_insignificant`	The wording difference is unlikely to produce meaningfully different response distributions. Either phrasing should work.
`uncertain`	The model cannot confidently predict whether the difference matters. Consider running a small pilot test.
`likely_significant`	The phrasing difference is likely to produce meaningfully different results. Review the reasoning and reconsider the wording before launching.

Use Cases

A/B Testing Question Wording

Before launching a survey, compare candidate phrasings to catch bias issues early:

// JavaScript example
async function comparePhrasings(surveyId, phrasingA, phrasingB) {
  const response = await fetch(
    `https://surventrics.ai/api/v1/surveys/${surveyId}/pretest/compare`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ phrasingA, phrasingB, category: 'question_wording' })
    }
  );

  const data = await response.json();

  if (data.recommendation === 'likely_significant') {
    console.log('Significant difference detected!');
    console.log(`Predicted effect: ${data.predictedEffect}pp`);
    console.log('Reasoning:', data.reasoning);
  }
}

Batch Pre-Testing

Iterate over all questions in a survey and pre-test alternative phrasings. Keep in mind the rate limit of 10 requests per minute.

// Pre-test all questions with alternatives
for (const question of questions) {
  if (question.alternativePhrasing) {
    const result = await comparePhrasings(
      surveyId,
      question.text,
      question.alternativePhrasing
    );

    console.log(`${question.text}`);
    console.log(`  -> ${result.recommendation} (effect: ${result.predictedEffect}pp)`);
  }
}

Name

Type

Description

id

string

Survey ID (UUID)

Name

Type

Description

phrasingA

string

First question phrasing (required, max 2000 chars)

phrasingB

string

Second question phrasing (required, max 2000 chars)

category

string

Pre-test category (required). See category values below.

audience

string

Optional free-text description of the target audience (max 500 chars) for additional model context.

Value

Description

question_wording

Differences in the wording or phrasing of the question

scale_labeling

Differences in the response-scale labels or anchors

question_order

Differences in the ordering of questions or items

response_options

Differences in the answer options offered

survey_length

Differences related to overall survey length

tone_formality

Differences in tone or formality of the language

other

Any other difference between the two phrasings

curl -X POST "https://surventrics.ai/api/v1/surveys/SURVEY_ID/pretest/compare" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phrasingA": "How satisfied are you with our service?", "phrasingB": "How would you rate your experience with our service?", "category": "question_wording", "audience": "Recent customers (last 30 days)" }'

{ "predictedEffect": 1.4, "confidenceInterval": { "lower": 0.2, "upper": 3.1 }, "recommendation": "likely_insignificant", "reasoning": "Both phrasings target the same construct (service evaluation) using similar scales. The shift from 'satisfied' to 'rate your experience' is unlikely to produce a meaningfully different response distribution.", "category": "question_wording", "model": "claude-sonnet-4-6", "latencyMs": 1820 }

Response Fields

Name	Type	Description
`predictedEffect`	number	Predicted absolute effect of switching phrasings, in percentage points.
`confidenceInterval`	object	95% confidence interval for the predicted effect: { lower, upper } (percentage points).
`recommendation`	string	Prediction result (see values below)
`reasoning`	string	Short (2-3 sentence) model explanation of the prediction.
`category`	string	The category that was supplied in the request.
`model`	string	Identifier of the model that produced the prediction.
`latencyMs`	number	Server-side prediction latency in milliseconds.

Recommendation Values

Value	Meaning
`likely_insignificant`	The wording difference is unlikely to produce meaningfully different response distributions. Either phrasing should work.
`uncertain`	The model cannot confidently predict whether the difference matters. Consider running a small pilot test.
`likely_significant`	The phrasing difference is likely to produce meaningfully different results. Review the reasoning and reconsider the wording before launching.

Use Cases

A/B Testing Question Wording

Before launching a survey, compare candidate phrasings to catch bias issues early:

// JavaScript example async function comparePhrasings(surveyId, phrasingA, phrasingB) { const response = await fetch( `https://surventrics.ai/api/v1/surveys/${surveyId}/pretest/compare`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ phrasingA, phrasingB, category: 'question_wording' }) } ); const data = await response.json(); if (data.recommendation === 'likely_significant') { console.log('Significant difference detected!'); console.log(`Predicted effect: ${data.predictedEffect}pp`); console.log('Reasoning:', data.reasoning); } }

Batch Pre-Testing

Iterate over all questions in a survey and pre-test alternative phrasings. Keep in mind the rate limit of 10 requests per minute.

// Pre-test all questions with alternatives for (const question of questions) { if (question.alternativePhrasing) { const result = await comparePhrasings( surveyId, question.text, question.alternativePhrasing ); console.log(`${question.text}`); console.log(` -> ${result.recommendation} (effect: ${result.predictedEffect}pp)`); } }