Quickstart: Focus Groups

What You’ll Learn

In this quickstart you will:

Understand synthetic focus groups: AI personas answer your questions at scale, so you get segment-level feedback without recruiting real users.
Gather prerequisites: API key, workspace ID, and at least two persona IDs.
Create a focus group with a name, sample size, persona list, and a short set of questions (e.g. NPS, Likert, open-ended).
Retrieve the completed focus group and read aggregated results (NPS score, summaries, individual responses).
Interpret the output so you can act on it (e.g. product or messaging decisions).

Focus groups are ideal for validating messaging, concepts, or product features before a full launch—with results in minutes instead of weeks.

Time: About 15 minutes (creation is quick; completion can take 1–5 minutes depending on sample size and question count). Credits: Roughly 50–200 credits depending on sample size and questions.

Prerequisites

Mavera account with an active subscription and enough credits. Focus groups typically use 50–200 credits per run.

API key from Developer Settings.

Workspace ID for the workspace where the focus group will live. You can find it in the app URL when viewing a workspace (e.g. app.mavera.io/workspaces/ws_abc123) or via the workspaces API.

At least two persona IDs from GET /personas. Use personas that match your target segments (e.g. Gen Z, Millennial Professional, B2B Decision Maker).

If you don’t have a workspace yet, create one in the Mavera dashboard; the API can also list workspaces if your account exposes that endpoint.

What Is a Synthetic Focus Group?

A focus group in Mavera is a single run where:

You define a sample size (e.g. 25 or 50).
You select personas (e.g. Gen Z Consumer, Millennial Professional). Each “respondent” is one of these personas.
You define questions with types such as NPS (0–10), Likert (agree/disagree), multiple choice, or open-ended.
Mavera simulates that many responses from the chosen personas and returns:
- Aggregated metrics (e.g. NPS score, % promoters/detractors, average Likert).
- Per-question summaries and, where applicable, individual responses with reasoning.

You get the kind of feedback you’d expect from a live focus group, without recruiting or scheduling.

Step 1: Get Your Persona IDs and Workspace ID

You’ll need 2+ persona IDs and your workspace ID. Listing personas is free (0 credits).

import requests

API_KEY = "mvra_live_your_key_here"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
BASE = "https://app.mavera.io/api/v1"

# List personas
personas_resp = requests.get(f"{BASE}/personas", headers=HEADERS)
personas_data = personas_resp.json()
personas = personas_data["data"]

# Pick a few; use their IDs in the focus group
for p in personas[:5]:
    print(f"{p['name']}: {p['id']}")

# You need a workspace_id — get it from the dashboard or workspaces API
WORKSPACE_ID = "ws_your_workspace_id"

const API_KEY = "mvra_live_your_key_here";
const HEADERS = { Authorization: `Bearer ${API_KEY}` };
const BASE = "https://app.mavera.io/api/v1";

const personasRes = await fetch(`${BASE}/personas`, { headers: HEADERS });
const { data: personas } = await personasRes.json();

personas.slice(0, 5).forEach((p) => console.log(`${p.name}: ${p.id}`));

const WORKSPACE_ID = "ws_your_workspace_id";

# List personas
curl -s https://app.mavera.io/api/v1/personas \
  -H "Authorization: Bearer mvra_live_your_key_here" | jq '.data[:3] | .[] | {name, id}'

Replace ws_your_workspace_id with the workspace where you want the focus group. Replace the placeholder persona IDs in the next step with real IDs from this list.

Step 2: Create the Focus Group

Send a POST with a name, sample size, persona IDs, and questions. Each question has a type, question text, order, and for some types (e.g. MULTIPLE_CHOICE) an options array.

focus_group_payload = {
    "name": "Quickstart: Product Launch Feedback",
    "sample_size": 25,
    "persona_ids": [
        "clx1abc2d0001abcdef123456",  # Replace with real IDs from Step 1
        "clx2def3e0002ghijkl789012",
    ],
    "workspace_id": WORKSPACE_ID,
    "questions": [
        {
            "question": "How likely are you to recommend this product to a friend? (0 = not at all, 10 = extremely likely)",
            "type": "NPS",
            "order": 1,
        },
        {
            "question": "The product design feels modern and appealing.",
            "type": "LIKERT",
            "order": 2,
        },
        {
            "question": "Which feature would you use first?",
            "type": "MULTIPLE_CHOICE",
            "options": ["Dashboard", "Reports", "Integrations", "Support"],
            "order": 3,
        },
        {
            "question": "What would make you more likely to purchase?",
            "type": "OPEN_ENDED",
            "order": 4,
        },
    ],
}

create_resp = requests.post(
    f"{BASE}/focus-groups",
    headers=HEADERS,
    json=focus_group_payload,
)
fg = create_resp.json()

if "error" in fg:
    raise Exception(fg["error"]["message"])

focus_group_id = fg["id"]
status = fg["status"]
print(f"Focus group created: {focus_group_id}")
print(f"Status: {status}")

const focusGroupPayload = {
  name: "Quickstart: Product Launch Feedback",
  sample_size: 25,
  persona_ids: [
    "clx1abc2d0001abcdef123456",
    "clx2def3e0002ghijkl789012",
  ],
  workspace_id: WORKSPACE_ID,
  questions: [
    {
      question: "How likely are you to recommend this product to a friend? (0 = not at all, 10 = extremely likely)",
      type: "NPS",
      order: 1,
    },
    {
      question: "The product design feels modern and appealing.",
      type: "LIKERT",
      order: 2,
    },
    {
      question: "Which feature would you use first?",
      type: "MULTIPLE_CHOICE",
      options: ["Dashboard", "Reports", "Integrations", "Support"],
      order: 3,
    },
    {
      question: "What would make you more likely to purchase?",
      type: "OPEN_ENDED",
      order: 4,
    },
  ],
};

const createRes = await fetch(`${BASE}/focus-groups`, {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify(focusGroupPayload),
});
const fg = await createRes.json();

if (fg.error) throw new Error(fg.error.message);

const focusGroupId = fg.id;
console.log("Focus group created:", focusGroupId);
console.log("Status:", fg.status);

curl -X POST https://app.mavera.io/api/v1/focus-groups \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart: Product Launch Feedback",
    "sample_size": 25,
    "persona_ids": ["clx1abc2d0001abcdef123456", "clx2def3e0002ghijkl789012"],
    "workspace_id": "ws_your_workspace_id",
    "questions": [
      {"question": "How likely are you to recommend this product? (0-10)", "type": "NPS", "order": 1},
      {"question": "The product design feels modern.", "type": "LIKERT", "order": 2},
      {"question": "What would make you more likely to purchase?", "type": "OPEN_ENDED", "order": 3}
    ]
  }'

The response includes id and status. Status is often PENDING or RUNNING at first; it moves to COMPLETED when all simulated responses are done.

Start with a small sample_size (e.g. 10–25) and 3–5 questions to keep credits and wait time low. You can increase both once you’re comfortable with the API.

Step 3: Wait for Completion and Fetch Results

Focus groups run asynchronously. Poll GET /focus-groups/{id} until status is COMPLETED, then read results.

import time

def get_focus_group(fg_id):
    r = requests.get(f"{BASE}/focus-groups/{fg_id}", headers=HEADERS)
    return r.json()

# Poll until completed (with a safety limit)
for _ in range(60):
    fg = get_focus_group(focus_group_id)
    if "error" in fg:
        raise Exception(fg["error"]["message"])
    if fg.get("status") == "COMPLETED":
        break
    time.sleep(5)
else:
    raise Exception("Focus group did not complete in time")

# Inspect results
for q in fg["results"]:
    print(f"\n--- {q['question']} ({q['type']}) ---")
    print(f"Summary: {q.get('summary', 'N/A')[:200]}...")
    if q.get("type") == "NPS":
        print(f"NPS Score: {q.get('nps_score')}")
        print(f"Promoters: {q.get('promoters')}% | Passives: {q.get('passives')}% | Detractors: {q.get('detractors')}%")
print(f"\nCredits used: {fg.get('usage', {}).get('credits_used')}")

async function getFocusGroup(id) {
  const r = await fetch(`${BASE}/focus-groups/${id}`, { headers: HEADERS });
  return r.json();
}

let fg;
for (let i = 0; i < 60; i++) {
  fg = await getFocusGroup(focusGroupId);
  if (fg.error) throw new Error(fg.error.message);
  if (fg.status === "COMPLETED") break;
  await new Promise((r) => setTimeout(r, 5000));
}
if (fg.status !== "COMPLETED") throw new Error("Focus group did not complete in time");

fg.results.forEach((q) => {
  console.log(`\n--- ${q.question} (${q.type}) ---`);
  console.log("Summary:", (q.summary || "N/A").slice(0, 200) + "...");
  if (q.type === "NPS") {
    console.log("NPS Score:", q.nps_score);
    console.log(`Promoters: ${q.promoters}% | Passives: ${q.passives}% | Detractors: ${q.detractors}%`);
  }
});
console.log("\nCredits used:", fg.usage?.credits_used);

# Poll (replace fg_abc123 with your focus group id)
curl -s "https://app.mavera.io/api/v1/focus-groups/fg_abc123" \
  -H "Authorization: Bearer mvra_live_your_key_here" | jq '{status, results: .results | length, usage}'

Step 4: Interpret the Results

Each element in results corresponds to one question and typically includes:

Field	Description
`question`	The question text.
`type`	Question type (NPS, LIKERT, MULTIPLE_CHOICE, OPEN_ENDED, etc.).
`summary`	AI-generated summary of how the segment responded.
For NPS	`nps_score`, `promoters`, `passives`, `detractors` (percentages).
For LIKERT	Scale distribution or average.
For MULTIPLE_CHOICE	Counts or percentages per option.
`responses`	Optional array of individual responses (persona, score/reasoning).

Example (simplified) for one NPS question:

{
  "question_id": "q1",
  "question": "How likely are you to recommend this product?",
  "type": "NPS",
  "nps_score": 42,
  "promoters": 55,
  "passives": 32,
  "detractors": 13,
  "summary": "Strong positive sentiment with Gen Z showing highest likelihood to recommend...",
  "responses": [
    {
      "persona_name": "Gen Z Consumer",
      "score": 9,
      "reasoning": "The product aligns with my values..."
    }
  ]
}

Use summary for a quick read; use responses and segment-level metrics when you need to compare personas or drill into outliers.

Question Types at a Glance

Type	Purpose	Typical response fields
`NPS`	Net Promoter Score 0–10	`nps_score`, `promoters`, `passives`, `detractors`
`LIKERT`	5-point agreement	Scale value, distribution
`MULTIPLE_CHOICE`	Single or multi-select	Selected option(s), counts
`OPEN_ENDED`	Free text	Summary, individual responses
`RATING`	Star rating 1–5	Rating, explanation
`YES_NO`	Binary	Yes/No, reasoning

For the full set (e.g. RANKING, SLIDER, MATRIX, SEMANTIC_DIFFERENTIAL, CONJOINT, MAXDIFF), see Focus Groups.

Credit Costs

Sample size	Approximate credits
10–25	50–75
26–50	75–125
51–100	125–200
100+	200+

Cost also depends on the number and complexity of questions. Check usage.credits_used on the completed focus group object.

Common Issues

Invalid workspace_id or 403

Ensure the workspace exists and your API key has access. Get the ID from the dashboard or workspaces API.

Invalid persona_id

Use IDs from GET /personas. You need at least one persona; two or more give more useful segment variation.

MULTIPLE_CHOICE missing options

For type: "MULTIPLE_CHOICE" you must include an options array of strings.

Focus group stuck in PENDING/RUNNING

Large sample sizes or many questions take longer. Poll for up to 5–10 minutes; if it never completes, check status or contact support.

402 credits_exhausted

Refill credits or reduce sample size / question count. See Credits.

Next Steps

Run First Focus Group

Full tutorial with Python/JS scripts

Focus Groups

All 12 question types, best practices

Persona Selection

Choose personas by use case

API Reference

Full request/response specification

Once you’re comfortable with one run, try varying personas and question mixes to simulate different segments (e.g. B2B vs consumer) or add more quantitative vs qualitative questions.

Getting Started

Core Concepts

Features

SDKs & Libraries

Quickstart: Focus Groups

What You’ll Learn

Prerequisites

What Is a Synthetic Focus Group?

Step 1: Get Your Persona IDs and Workspace ID

Step 2: Create the Focus Group

Step 3: Wait for Completion and Fetch Results

Step 4: Interpret the Results

Question Types at a Glance

Credit Costs

Common Issues

Next Steps

Run First Focus Group

Focus Groups

Persona Selection

API Reference

​What You’ll Learn

​Prerequisites

​What Is a Synthetic Focus Group?

​Step 1: Get Your Persona IDs and Workspace ID

​Step 2: Create the Focus Group

​Step 3: Wait for Completion and Fetch Results

​Step 4: Interpret the Results

​Question Types at a Glance

​Credit Costs

​Common Issues

​Next Steps

Run First Focus Group

Focus Groups

Persona Selection

API Reference

What You’ll Learn

Prerequisites

What Is a Synthetic Focus Group?

Step 1: Get Your Persona IDs and Workspace ID

Step 2: Create the Focus Group

Step 3: Wait for Completion and Fetch Results

Step 4: Interpret the Results

Question Types at a Glance

Credit Costs

Common Issues

Next Steps