Once a simulation finishes, Boses produces two layers of output: per-persona results (what each individual said and felt) and an aggregate result (what it means across the group). This page explains how to poll for completion and how to read both layers.
Polling simulation status
Simulations run as background tasks. After creating one, poll GET /simulations/{id} until the status field reaches "complete".
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations/<SIM_ID> \
-H "Authorization: Bearer <access_token>"
Status progression
| Status | Meaning |
|---|
pending | Simulation is queued and waiting to start. |
running | Personas are actively generating responses. |
generating_report | All persona responses are done; the aggregate report is being compiled. |
complete | Results are ready to fetch. |
failed | The simulation encountered an unrecoverable error. |
aborted | You cancelled the simulation via the abort endpoint. |
progress field updates in real time during running:
{
"id": "sim_01hw4n7zxe2fqv3brc5e",
"status": "running",
"progress": {
"completed": 3,
"total": 5
}
}
Individual persona failures are non-fatal. If one persona fails but the others succeed, the simulation continues and the aggregate is computed from the successful responses. Only if every persona fails does the simulation status become "failed".
Fetching results
Once status is "complete", retrieve the full results:
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations/<SIM_ID>/results \
-H "Authorization: Bearer <access_token>"
Result structure: concept test
The following shows the full response structure for a concept_test simulation.
{
"simulation_id": "sim_01hw4n7zxe2fqv3brc5e",
"simulation_type": "concept_test",
"persona_results": [
{
"persona_id": "per_01hw2j8zxe1fmv4bqc3a",
"persona_name": "Maria Santos",
"result_type": "concept_test_individual",
"reaction": "I actually like the idea of the chili-lime flavour — it feels fresh and different from the usual BBQ options. The eco-friendly packaging is a nice touch, but I'd want to see if it's actually sturdier than the old one. At PHP 45 I'd still buy it, but only if it's the same size as before.",
"sentiment": "Positive",
"key_themes": [
"flavour novelty",
"packaging scepticism",
"price sensitivity",
"size expectations"
],
"notable_quote": "It feels fresh and different — but I need the portion size to match the price."
},
{
"persona_id": "per_01hw2j8zxe1fmv4bqc3b",
"persona_name": "Carlo Reyes",
"result_type": "concept_test_individual",
"reaction": "Honestly, chili-lime is overdone. Every brand is doing a variant like this. The eco-packaging sounds like marketing to me — I've seen brands say that and the bag still ends up in the trash. PHP 45 is fine but I'm not switching from my usual brand for this.",
"sentiment": "Negative",
"key_themes": [
"flavour fatigue",
"greenwashing scepticism",
"brand loyalty",
"competitive alternatives"
],
"notable_quote": "Every brand is doing a variant like this — what makes yours different?"
}
],
"aggregate_result": {
"result_type": "concept_test_aggregate",
"sentiment_distribution": {
"Positive": 3,
"Neutral": 1,
"Negative": 1
},
"top_themes": [
"price-to-size value",
"flavour novelty vs. fatigue",
"eco-packaging credibility",
"brand switching resistance"
],
"strategic_recommendations": "The concept has a positive lean (3/5), driven by flavour novelty and eco credentials among younger segments. However, credibility of the eco claim is a recurring concern — substantiate it with specific material or certification details in packaging and comms. The price point is broadly acceptable, but size consistency relative to the previous SKU is a threshold condition for repurchase. Messaging should lead with the flavour story, not the sustainability angle, to avoid greenwashing associations."
}
}
Understanding per-persona results
Each persona result contains four fields:
| Field | Description |
|---|
reaction | A first-person response written in the persona’s voice. This is the raw qualitative output. |
sentiment | Overall sentiment of the response: "Positive", "Neutral", or "Negative". |
key_themes | A list of themes the persona raised in their response. Used to compute the aggregate top_themes. |
notable_quote | A short, presentation-ready quote extracted from the reaction. |
Understanding the aggregate result
The aggregate result synthesises responses across the whole group:
| Field | Description |
|---|
sentiment_distribution | Count of Positive, Neutral, and Negative responses across all personas. |
top_themes | The most common themes across all per-persona key_themes lists. |
strategic_recommendations | An LLM-generated narrative that interprets the findings and suggests action. |
Result structures for other simulation types
Different simulation types produce different result shapes. The fields above apply to concept_test. Other types have their own structures:
| Simulation type | Per-persona result type | Aggregate result type | Notable differences |
|---|
concept_test | concept_test_individual | concept_test_aggregate | Reaction, sentiment, themes, quote |
survey | survey_individual | survey_aggregate | Per-question distributions for likert/multiple-choice; open-ended theme extraction |
focus_group | focus_group_individual | focus_group_aggregate | Two rounds of responses; moderator summary; consensus and disagreement themes |
idi_ai | idi_individual | idi_aggregate | Full transcript per persona; structured analysis of attitudes and motivations |
conjoint | conjoint_individual | conjoint_aggregate | Part-worth utilities per attribute level; attribute importance rankings; market share simulation |
Run a concept test first to get a directional read quickly. Use focus groups or in-depth interviews to probe the specific themes that surface in the concept test aggregate.
