Asking questions

Everything about POST /v1/ask: who answers, what you can ask and what comes back.

Who answers: target

Set exactly one of these:

Field	Who answers
audience	An audience in your own words, e.g. "UK, 18-30, fitness enthusiasts". We find matching Twins for you.
audienceId	A saved audience (id from GET /v1/audiences).
studyId	The participants of one of your studies (GET /v1/studies). Each Twin answers with its person's whole study conversation in context.

Sample size

sampleSize sets how many participants answer: 1–200, and at most 100 for audiences.

Target	Default
Described audience	25
Saved audience	Everyone, up to 100
Interview study	Everyone
Twin-survey study	25

Narrowing a study

For study targets only:

• filter: free text matched against each participant's profile and what they said, e.g. "said price was the main barrier".
• twinIds: specific participants, from GET /v1/studies/{studyId}/participants.

What to ask: questions

Up to 15 questions, open and choice mixed. Each participant answers them in order in one conversation, so a later question can follow up on an earlier one.

{
  "target": { "audience": "UK, 18-30, fitness enthusiasts" },
  "questions": [
    {
      "id": "pick",
      "type": "choice",
      "question": "Which is most important when buying running shoes?",
      "choices": ["Price", "Comfort", "Style", "Durability"]
    },
    { "id": "why", "type": "open", "question": "Why did you pick that?" }
  ]
}

Field	Notes
type	open for free text, choice for options.
question	Up to 2,048 characters. Paste any copy or concept you're testing right into it.
choices	Choice only: 2–20 distinct options.
isMultipleChoice	Choice only: true lets participants pick several.
id	Optional key for this question in the answers. Defaults to q1, q2, …

The response

{
  "requestId": "…",
  "data": {
    "source": { "type": "audience", "id": null, "description": "UK, 18-30, fitness enthusiasts" },
    "total": 30,
    "matched": 30,
    "asked": 25,
    "questions": [
      {
        "id": "pick",
        "type": "choice",
        "question": "Which is most important when buying running shoes?",
        "choices": ["Price", "Comfort", "Style", "Durability"],
        "isMultipleChoice": false,
        "answered": 25,
        "results": [
          { "choice": "Price", "count": 7, "percentage": 27 },
          { "choice": "Comfort", "count": 12, "percentage": 41 },
          { "choice": "Style", "count": 2, "percentage": 12 },
          { "choice": "Durability", "count": 4, "percentage": 20 }
        ]
      },
      { "id": "why", "type": "open", "question": "Why did you pick that?", "answered": 25 }
    ],
    "participants": [
      {
        "twinId": "…",
        "demographics": { "age": 27, "gender": "Female", "country": "GB" },
        "answers": {
          "pick": {
            "selections": ["Comfort"],
            "confidence": "high",
            "reason": "Runs most mornings and has had shin pain from cheap pairs."
          },
          "why": { "answer": "I run most mornings, so…", "confidence": "high" }
        }
      }
    ]
  },
  "error": null
}

What each field means

• participants[].answers is keyed by question id. A missing key means that participant didn't answer.
• confidence is low, medium or high: how much the answer rests on the Twin's own data about the topic rather than demographics alone. Choice answers also carry a reason.
• questions[].results (choice only): count is how many picked each option. percentage is the option's average probability across participants (0–100), which is steadier than raw counts. For multi-select questions, percentages can add up to more than 100.
• asked is how many participants answered. total is the number of participants in the study or audience, and matched is how many matched your filter and twinIds.
• twinId is new on every request for audiences, so Twins can't be linked across calls. For studies, it's the participant's id, which you can pass back as twinIds.

Saved audiences

Save an audience to ask the same Twins every time, then pass its id as "target": { "audienceId": "…" }. See Audiences in the reference.

Billing

You pay per answer: participants × questions. A 5-question ask to 25 participants is 125 answers.