Skip to main content
A study is the durable thing you keep coming back to. You make something, point a study at it, and simulated people experience it and report back. Then you change the thing, run the study again, and compare. The study persists across all of that. The runs come and go. Think of a study as the question you are asking, held steady while the answer gets refined. “Does the onboarding land for first-time visitors?” is a study. The five variations of the onboarding you try, and the panels you run against each, are not the study. They live inside it.

​
What a study holds

A study is the recipe, not the dish. It defines how an experience should be observed, and it does not carry the link or file being observed. That separation is the whole point: it lets one study outlive many drafts of the thing it tests. A study carries:
  • A modality: the kind of artifact simulated people experience. One of interactive (they drive a real browser), text, video, audio, image, document (they read, watch, or listen and react), or chat (a multi-turn conversation). The modality is fixed when the study is created and decides the mechanics of every run.
  • A content type for media studies (for example email, ad, social_post). It frames what the simulated person is looking at, so a draft read as an email is observed differently from the same words read as a blog post.
  • Assignments: the tasks each simulated person attempts (sign up, skim the article, find the price). See assignments.
  • Interview questions: the free-text questions each person answers after the experience. See questionnaire.
What a study does not hold is the URL, the file, or the chatbot endpoint being tested. That belongs to its iterations.

​
Studies, iterations, and runs

The piece a study deliberately leaves out (the concrete thing under test) lives on an iteration. An iteration attaches one URL, one media file, or one chatbot endpoint, and it is the unit that actually gets executed. A study has one or more iterations, labelled A, B, C, and so on. Two iterations on the same study are how you A/B a change: same assignments, same questions, different artifact. A run dispatches a panel of simulated people against one iteration. The run draws on your workspace credits and produces the reactions: a reported journey per person, with sentiment, friction, blockers, positive moments, completion, and the reasoning behind each. Runs accumulate on the iteration. The study and its iterations stay put.
The split is recursive. The study is the persistent question, the iteration is the persistent variant, and a run is one transient observation of that variant. Drafts move; the study holds the line.
A study always belongs to exactly one workspace. Delete the workspace and its studies go with it.

​
The loop a study is built for

A study earns its persistence by being run more than once. Its normal shape is a cycle, not a one-shot. The study sets the question once, fixing the modality, assignments, and questions. An iteration points it at the first draft. A run dispatches a panel and the reactions come back. Then the draft changes, a new iteration captures the change, another run reads the reactions again, and the two iterations sit side by side so you can see whether the change landed. You are not setting up a fresh experiment each time. You are keeping one question open and watching the answer move as the work improves. That is why the study, not the run, is the unit you name, save, and share.

​
Two ways to drive a study

Studies are first-class on both developer surfaces, and the verbs line up: the study you create, the iteration you attach, the run you dispatch, and the reactions you read are the same four moves on the CLI and through MCP. The example below shows the parity, not a procedure to follow step by step. 
# Create the study (the recipe), with zero iterations
ish study create \
  --name "Onboarding UX" \
  --modality interactive \
  --assignment "Sign up:Complete the signup flow" \
  --question "How easy was it?"

# Attach the thing under test, then run a panel against it
ish iteration create --url https://example.com
ish study run --sample 5 --country SE -y

# Read the reactions
ish study results s-b2c
A study created without any inline content starts with zero iterations on purpose: there is no placeholder draft to run against by accident. Add the first iteration when you have something concrete to show.

​
Lifecycle

A study moves through a small set of states: draft, running, completed, and cancelled. The state reflects the study as a whole, aggregated from the runs on its iterations. Two studies can also be linked. Cloning a study for benchmarking (running the same recipe against several brand workspaces) records the original it was copied from, so the comparison keeps its lineage.

​
Where to go next

Iterations

The variants inside a study: each one carries the URL, media, or endpoint a run executes against.

Modalities

The seven kinds of artifact a study can observe, and what each changes about a run.

study commands

Every CLI flag for study create, study run, and reading results.

study tools

The MCP study tool space: parameters, return shapes, and views.