Test (studies, claims)

The Test group is where the bright line bites hardest: numbers come from fielding actual persona responses, never from a model guessing a percentage.

Tool	What it tests
`test_concept`	A product/feature concept.
`test_message` / `compare_messages`	One message, or A/B/n across messages.
`test_claims`	Specific claims for believability/appeal.
`test_pricing`	Willingness-to-pay / price structures.
`test_positioning` / `test_naming`	Positioning statements, names.
`test_creative` / `test_ad_placement` / `test_geography`	Creative, placement, geo.
`run_study` / `run_grounded_study`	A full multi-question study (grounded = evidence-anchored).
`field_with_variance`	Field with realistic response variance.
`compute_stats` / `synthesize_insight`	Statistics + insight synthesis over results.
`run_parity_check` / `get_parity_history` / `validate_with_humans`	Calibrate synthetic vs. human ground truth.
`map_jtbd` / `map_objections` / `find_feature_gaps` / `reconcile_advocacy`	Qual synthesis (jobs, objections, gaps).

Calibration matters. run_parity_check and validate_with_humans let you measure how closely your synthetic audience tracks real respondents, so you know how much to trust a result. Always sanity-check a synthetic study against known ground truth before betting on it.

Fielding studies safely

run_study and field_with_variance use the durable queue on the public API. The API persists a job before model work and returns HTTP 202 with a jobId. Send one unique Idempotency-Key for each intended study.

: "${MAVERA_API_KEY:?set MAVERA_API_KEY first}"

# 1) enqueue. A safe retry with the same key and body returns the same job.
curl -X POST https://app2.mavera.io/api/v1/tools/field_with_variance \
  -H "x-api-key: $MAVERA_API_KEY" \
  -H "Idempotency-Key: clyne-cell-920101" \
  -H "content-type: application/json" \
  --data '{"audienceId":"aud_f1_1","questions":[{"id":"q1","text":"..."}],"n":50,"seed":920101}'
# -> { "ok": true, "data": { "jobId": "sj_...", "status": "QUEUED", "poll": "/api/v1/studies/async?jobId=sj_..." } }

# 2) poll until DONE or FAILED.
curl "https://app2.mavera.io/api/v1/studies/async?jobId=sj_..." \
  -H "x-api-key: $MAVERA_API_KEY"

# 3) if the enqueue response was lost, recover the job from the original key.
curl https://app2.mavera.io/api/v1/studies/async \
  -H "x-api-key: $MAVERA_API_KEY" \
  -H "Idempotency-Key: clyne-cell-920101"

A background worker claims the job, fields it, settles billing once, and persists the resulting studyId. Keep each job to 100 respondents or fewer and at most two questions. Split larger designs into separately seeded bounded waves. Do not create a new key for a retry of the same intended study. Reusing one key with a different payload returns HTTP 409.

Study counts are explicit. n and respondentCount mean distinct respondents. responseRowCount means respondent-question answer rows, so a 50-person study with two questions has respondentCount: 50 and responseRowCount: 100.

Test (studies, claims)

Fielding studies safely

On this page