GET /v1/studies
List all active studies for your project.
Returns studies with their current usage, whether they’re accepting new responses, and a summary of each study’s Study Manager state (ledger_summary) so you can tell at a glance which study has moved.
Request
Bearer token. See Authentication.
active (default), paused, concluded, or all. Filters on the stored status; a stale or limit-reached study is active.ledger_summary is null for a study whose Study Manager has not saved yet. See Ledger summary for the fields. If a summary query fails on our side, the affected studies come back with ledger_summary: null and the list still succeeds.
GET /v1/studies/:id
Retrieve a single study with full details: what it set out to learn, who is interviewed, what the product is, the questions with their interviewer notes, and the interview count. Add expand=ledger to embed the study’s ledger in the same response.
Request
Bearer token. See Authentication.
ledger embeds the study’s current ledger as ledger: the same object GET /v1/studies/:id/ledger returns, active items only, or null before the Study Manager’s first save (not a 404). Without expand, the response has no ledger key. Any other value returns 400.404 if the study doesn’t exist or doesn’t belong to your project. Returns 400 with code "invalid_parameter" and param "expand" when expand is anything but ledger.
Study object
"active", "paused", or "concluded": the stored lifecycle, the one a person drives. A study is created active. Pausing and concluding stop the interview link admitting respondents; interviews already in progress finish, and the Study Manager still reviews them. Every move is a status_changed event on the study’s timeline with who made it.Public URL for respondents. Append
?reference_id=your_user_id to track who completes the interview.true exactly when state.value is "active" or "stale": the study is active and no limit has been reached. A paused or concluded study is never accepting, even within its limits.The one displayed state: the stored
status folded with the two things that stop or quiet a study without anyone touching it, a limit reached and silence. Computed on read.How the study’s completed interviews were graded. Every completed, non-test, non-deleted interview is scored once it is processed (or by hand on the Conversations page) and counts in exactly one of the four counts. A low
ratio says the study’s setup is not getting usable conversations (questions, audience, length), not that respondents think anything.Ledger summary (list only)
Each item ofGET /v1/studies carries ledger_summary: the study’s Study Manager state at a glance. The Study Manager is the agent that reads every quality interview and keeps the study’s ledger. The summary is null until the agent has saved its first version, so a study with no ledger is visibly a study with no ledger, never a quiet one. This is a summary, not the ledger: phase is the value alone, and the full object is only on the detail with expand=ledger.
Detail-only fields
These fields are only included inGET /v1/studies/:id responses:
What the person who concluded the study wrote: what it settled and what is left open.
null when the study was concluded without notes, and when it was never concluded. Written only by the conclude move (uj studies conclude <id> --notes "…", or notes on studies_set_status with to: "concluded"), where a blank note clears it; a reopened study keeps its last notes until it is concluded again. The same text is on the status_changed event as detail.notes.Interactive prototype the participant uses during the interview, or
null when the study has none. See Interactive prototype.The study’s own full-screen participant flow, or
null for the default flow. See Participant flow.Present only with
expand=ledger. The study’s current ledger, the same study ledger object as GET /v1/studies/:id/ledger with active items only, or null before the Study Manager’s first save. Unlike the ledger endpoint, a missing ledger is not a 404 here: the study detail is still returned.Interactive prototype
A study can embed a live web prototype in the interview instead of static screenshots. The switch is per study:prototype_config is null (off) or an object, set through the studies_config_update MCP tool or uj studies config set <id> --file config.json.
baseUrlmust be https (http is allowed only for localhost). The prototype publishes its valid{ screen, scenario }pairs atGET {baseUrl}/api/states.description(max 240 characters) is what the interviewer agent reads about the start state.prototypeis the prototype’s id: every message the prototype posts carries it assource, and the participant page accepts no other. Copy it fromGET {baseUrl}/api/states.screens(optional, up to 12 of{ id, description }) tells the agent what each screen of the prototype is and what the participant can do there, so it understands its live context notes. Copy thescreensarray fromGET {baseUrl}/api/states.flows(optional, up to 8 of{ task, steps }) tells the agent how common tasks are done, so it can guide a stuck participant. Copy it fromGET {baseUrl}/api/states.events(optional, up to 64 of{ token, meaning, use }) tells the agent what each of the prototype’s context notes means and how to act on it. Copy it fromGET {baseUrl}/api/states.task(optional,{ text, audioUrl, clipBeforeStartOnly?, imageUrl?, imageAlt?, imageBeforeStartOnly?, situation?, steps?, hint?, checkUnderstanding?, handOver? }) puts a task card on the participant’s screen before the prototype appears.text(max 280 characters) is the task as they read it.audioUrlis an https audio clip they can play from the card, ornullfor text only; with a clip, Start unlocks after one listen.clipBeforeStartOnly: true(optional, default off) offers the clip only before Start: the card says so, and the card reopened from the Task button shows the text only. Ignored whenaudioUrlisnull.imageUrl(optional) is an https picture shown on the card under the text; with a picture, Start unlocks once it has loaded or failed to load, so a broken URL never traps the participant.imageAlt(optional, max 280 characters) says what the picture shows, for screen readers.imageBeforeStartOnly: true(optional, default off) shows the picture only before Start: the card says so, and the reopened card has no picture. A Task button above the prototype brings the card back. The agent is told what the card says and receivestask_card=openedandreference_playednotes.steps(optional, 1 to 4 strings of up to 120 characters) makes the card readable at a glance: it showssituation(optional, max 160 characters) as a short scenario line in small type, the steps big and numbered, andhint(optional, max 160 characters, e.g. “Start from the search bar.”) small and muted under them, in place oftext, on the first card and when reopened.situationandhintare ignored withoutsteps.textstays required: it is the plain-text version of the same task, and it is what the agent is told the card says, so keep the two in step. A card withoutstepsshowstextas one paragraph, as before.checkUnderstanding: true(optional, default off) puts the task card before the prototype, so the interviewer can check that the participant understood the task (by default with one light question; seehandOverfor a longer check). Where the prototype would appear by itself after the introduction, the card appears on the call screen instead (the agent receivestask_card=briefing) and the prototype stays hidden. Tapping Start closes the card and brings them back to the call; the agent receivestask_card=startedand, at once, a turn (the page sends “I’ve read the task and tapped Start.” in the participant’s name; it is left out of the transcript), so it speaks first and asks one short question like “In a few words, what’s your task?”. WithhandOver: "reply"(the default) their answer is the check: the agent adds a missed part in one sentence if needed and hands over in at most two short sentences. The page then shows the prototype by itself, without a tool call: half a second after the interviewer stops talking, 8 seconds after their answer if it says nothing, and never later than 20 seconds after their answer, so the app does not appear mid-sentence. (APROTOTYPE_STARTfrom the agent after Start is held the same way.) Withmicrophonethe hand-over is a line like “Great, I’ll put you in the app now. Talk to the app, not to me, and I’ll come back with a few questions once you’re done.”; without it, “Great, here’s the app. Think aloud as you go.” So the study’s opening line should stay short and only point to the card (for example “Hi, I’m Alex. Your task is on the next screen. Have a read, then tap Start.”), and the question notes should not tell the agent to callPROTOTYPE_STARTbefore the check. WithstartOn: "agent"the card waits for the agent instead: itsPROTOTYPE_STARTbrings up the card (and the participant flow’s story), and the prototype still comes after the check. The prototype takes the microphone when it appears, as for any study. If they have not answered 30 seconds after Start (50 if the interviewer is still talking), the page shows it anyway (and sendsshown=start); withhandOver: "agent"the prototype instead waits for the interviewer’sPROTOTYPE_START, as described underhandOver. The Task button over the prototype works as usual. Off, nothing changes.handOver(optional,"reply"or"agent", default"reply"; only withcheckUnderstanding) says what ends the check after Start. With"reply"the check is one light question and the prototype appears as soon as the interviewer’s reply to the participant’s first answer is spoken. With"agent"the check is a short conversation that the study’s own instructions shape, with follow-ups, for example having the participant name what they will research and asking them to think of something else when it does not fit: their answer does not open the prototype, and it stays hidden until the interviewer callsPROTOTYPE_STARTin the turn with its hand-over, appearing once that is spoken. If the interviewer never calls it, the page shows the prototype 5 minutes after Start (5 minutes 20 seconds if the interviewer is still talking). Before Start,PROTOTYPE_STARTis refused with a result that tells the agent to wait (withstartOn: "agent"its first call still brings the card).
goal(optional,{ answer, description, timeLimitMinutes?, missLine? }) is for a task with a right answer that the prototype can check, such as a product to find.answer(max 240 characters) is what counts as reaching the goal, in the prototype’s own form; the participant page hands it to the prototype as thegoalquery parameter of the start URL.description(max 400 characters) says what the goal is, for the interviewer only: it never says or hints at it.timeLimitMinutes(optional, 1 to 60) is handed to the prototype as theminutesquery parameter; the prototype keeps the time.missLine(optional, max 160 characters) is the exact sentence the interviewer says after a try that missed; the default is “Good try, but that’s not the one. Have another go.” The interviewer never judges a try itself. It acts only on the prototype’s notes:goal=metends the hands-on part at once (it callsPROTOTYPE_ENDbefore speaking, then follows the study’s instructions),goal=missedgets the miss sentence and nothing else, andtime_up minutes=<n>ends the hands-on part. So the prototype must support it: decide what a try is, check each one againstgoal, and post those notes withturn: true(see Prototype messages). The study’s own instructions only need to say what happens after the hands-on part.startOn(optional,"auto"or"agent", default"auto") says when the hands-on part starts. With"auto"the prototype (or the understanding check’s card) appears by itself a few seconds after the introduction, with a fallback of 20 seconds after the call screen opens (40 if the interviewer is still talking). With"agent"the page shows nothing by itself: the interviewer callsPROTOTYPE_STARTat the moment the study’s instructions say, for example after a few opening questions, and the task card comes with the prototype. Withtask.checkUnderstanding,PROTOTYPE_STARTshows the task card (and the participant flow’s story) on the call screen once the agent has finished speaking, and the prototype still comes after the check.timeLimit(optional,{ minutes, settleSeconds?, settleText?, clock? }) gives the hands-on part a fixed length, kept by the participant page, for a task with no right answer.minutesis 1 to 60. The clock starts when the prototype is first on screen with the task card closed, stops while the call is paused, and stays in view as a timer pill in the top-left corner, over the prototype’s header: grey, orange in the last minute and red in the last stretch. In its lastsettleSeconds(0 to 120, default 30; 0 for none) a red bar under the header says “Time’s almost up. Make your final choice.”, orsettleText(up to 80 characters, e.g. “Say your pick out loud now.”) when the study sets it, and the interviewer receivessettle seconds_left=<n>. At zero the page ends the hands-on part itself, sendstime_up minutes=<n>and gives the interviewer a turn, so the study’s instructions only need to say what comes after. Participants cannot finish early: the page refuses the interviewer’sPROTOTYPE_ENDuntil the time is up, and the interviewer is told to say “You still have some time left. Use it as you would on your own.” once if they say they are done. Ignored whengoalis set, since a goal’s hands-on part ends when it is met.clockis"decide"(the default, as above) or"inform", a clock that only tells the time: the pill reads minutes only (“9 min”) until the last minute, then minutes and seconds, and stays grey; when the last minute starts, “1 minute left” shows under the header for 5 seconds. It has no last stretch, sosettleSecondsandsettleTextare ignored, and there is no settle bar and nosettlenote.activityKeepAlive(optional boolean, default off): whentrue, taps in the prototype count as activity on the call, so a participant who works without speaking is not ended by the silence timeout.microphone(optional boolean, default off): whentrue, the prototype may use the participant’s microphone, for a prototype they talk to. While the prototype is on screen it has the microphone and the interviewer does not hear the participant; the interviewer follows the prototype’s notes instead. When the prototype ends the call takes the microphone back (and stays muted if the participant had muted themselves before); if the microphone does not come back, the call stays muted and the participant sees the lost-microphone notice. So the study’s instructions must not rely on the interviewer hearing anything during the hands-on part, and the prototype should post what the participant said as notes (see Words spoken in the prototype). Because the interviewer hears nothing then, it takes no turn by itself: the page gives it one only when the prototype asks, withturn: trueon a message (see Prototype messages), about a second after that note is delivered. A prototype that never setsturnleaves the interviewer silent for the whole hands-on part, so it must ask for a turn wherever the study’s instructions expect the interviewer to act (for example to end the hands-on part). On such a turn the interviewer says only what the study’s instructions prescribe for that situation and otherwise stays silent (it skips the turn), so the instructions must spell out what to say. The page’s signal is not a participant turn and does not appear in the transcript; everything the interviewer says does. Using the prototype also counts as activity on the call, as withactivityKeepAlive. The prototype is loaded before it is shown, so it should ask for the microphone only once the participant starts using it.dictation(optional boolean, default off): whentrue, the prototype may borrow the participant’s microphone for a moment, for a dictation button in a prototype they mostly tap and type in. The interviewer keeps hearing the participant while the prototype is on screen, except while a dictation runs. The prototype asks for the microphone with{ source, type: "mic_hold", held: true }when the participant starts dictating, and must not start recording until the page answers{ source: "userjourneys-interviewer", type: "mic_hold", held: true }: on iOS only one capture runs at a time, and that answer means the call has let go. Once the prototype’s own capture has stopped it sendsheld: false, and the page answersheld: falsewhen the call has the microphone again. The page answers every request, so a prototype that gets no answer should give up on dictation. A request while the prototype is hidden is ignored, and hiding or ending the prototype hands the microphone back to the call. So the study’s instructions should not expect the interviewer to hear what was dictated; the prototype should post a note when a dictation starts and ends. Ignored whenmicrophoneistrue.bar(optional,"full"or"minimal", default"full"): how much of the interview bar the participant sees above the prototype."full"keeps the bar (Task button, microphone picker, mute, pause, leave) above the prototype at all times."minimal"is for a prototype that needs the whole height of a phone screen: while the participant is in the prototype, the bar is gone and the prototype runs to the top edge, with one small button in the top corner. Tapping that button lays the bar over the top of the prototype; it goes away again after about 5 seconds without a tap on it, on a second tap on the button, or when the participant goes back to the prototype. The bar is shown as with"full"on the task card (before Start and when reopened), while the call is paused, and whenever the call has something to tell the participant (connecting, reconnecting, a microphone or connection notice, an error). The small orb that shows the interviewer’s turn is not shown while the bar is hidden.- The agent receives exactly two stimulus ids for the prototype:
PROTOTYPE_STARTshows it,PROTOTYPE_ENDhides it. Question notes must say when to call them, for example “Call PROTOTYPE_START now and keep it visible until the last question.” - While the prototype is visible, the participant’s actions are summarised to the agent as short context notes and recorded in the interview’s session replay. The prototype writes those notes itself; see Prototype messages.
Prototype messages
The prototype posts one message per interaction towindow.parent:
sourcemust equalprototype_config.prototype;typeis the prototype’s own event name;ts,seqandsessionIdidentify the message.note(max 280 characters) is what the agent reads.eventsin the study config explains every note.detail(optional, max 8,000 characters): the full text behind the note, for example a whole chatbot answer behindreply_done chars=3040. It reaches the agent at once as its own[proto] <note> detail: …update (led by its note, so the two stay tied), outside the batching and the 12-a-minute limit, except on anactivitymessage, which sends nothing, and is kept whole in the interview transcript. The agent is told to use it to know what the participant saw and never to read it out. Keep the note short and put long text here.delivery:now(default) sends the note;activitysends nothing and only shows the participant is busy, so the agent is not told they are idle. Anowmessage without a note reaches the agent asevent=<type>.merge: a key; a newer note with the same key replaces the pending one, e.g. typing sendstyped=12thentyped=40and the agent receivestyped=40.state: values that open every note,on=<screen>first (null removes a key).turn(optional boolean, default off):trueasks the page to give the interviewer a turn to act on this note. It only matters in a study withmicrophone: true, while the prototype is on screen; otherwise the interviewer takes its turns by itself. The request stays with the note until it is delivered, and is ignored on anactivitymessage. Without it the note is delivered silently.- Notes are batched (1.5 s), repeats collapse to
x<n>, and the agent receives at most 12 updates a minute. After 20 seconds without any message the agent is toldidle=<s>.
Words spoken in the prototype
Two note forms are reserved for words, and they are what puts the hands-on part into the researcher’s transcript:said_to_app "<text>": something the participant said or typed to the prototype.app_said "<text>": something the prototype said or showed back in words.
- The note is exactly the keyword, a space, then the text in double quotes, and nothing after the closing quote. One note carries one utterance; post a second message for the next one. A keyword in the middle of another note (
heard said_to_app "…") or with=(said_to_app="…") is not speech. - Escape a double quote inside the text as
\"and a backslash as\\. Unescaped inner quotes are tolerated: the text runs to the last quote of the note. ;,[,],<and>in a note are replaced with,before it is sent, and line breaks with a space, so the transcript shows the text that way.- A note is cut at 280 characters including the keyword, so about 265 characters of text. A cut note still shows, ending in ”…”. Split a long utterance into several notes, sentence by sentence.
- Do not set
mergeon these notes (a newer note would replace the earlier words), and send each sentence once: identical notes in one batch collapse into one line. - A batch holds 480 characters. When more arrives in 1.5 s, later notes are dropped from the batch (counted as
+N) and never reach the transcript; a note withturn: trueis kept first. - A line’s time is when its batch reached the interview page, a second or two after the words were said; all lines of one batch share that time.
Recording the participant’s voice during the task
In a study withmicrophone: true the call does not hear the participant while the prototype is on screen, so their voice during the task is in no recording unless the prototype sends it. The prototype can post what its own microphone captures to window.parent, with the ArrayBuffer in the transfer list:
- A segment is one continuous recorder run (for example one
MediaRecorderstarted with a timeslice). Its parts, joined inpartorder, must be one playable file. Start a new segment, with the nextsegmentnumber andpartback at0, every time the microphone is turned on again. segment: whole number from 0 to 49.part: whole number from 0, counting up by one with no gaps. A part that arrives out of order ends that segment: nothing after it is stored.startedAt: the time the segment’s first audio was captured, in epoch milliseconds on the participant’s device (Date.now()). Send the same value with every part of a segment. It is what places the audio on the replay, and together withsegmentit identifies the recording: a part that reuses a segment number with anotherstartedAtormimeis a different recording and is never added to the first one. If the prototype reloads and counts from 0 again, the page stores the new recording under the next free segment number.mime: the recorder’s type. It must start withaudio/, be at most 80 characters, and use only lowercase letters, digits, spaces and/ ; = . + -(soaudio/webm;codecs=opusandaudio/mp4, but no quotes or capitals).data: anArrayBufferof 1 byte to 512 KiB. Send a part about every 4 seconds.source,ts,seqandsessionIdare the same as on every other message.- Limits per interview: 50 segments and 40 MiB in total. Audio past a limit is dropped.
- A
mic_audiomessage is accepted only in a study withmicrophone: true; otherwise it is dropped. It is never a note: the interviewer agent does not receive it and it does not count as activity. - The audio is stored with the interview. In Conversation history, when the session replay is shown, it plays inside the replay in step with the screen (and with the call audio when there is one). A Task audio button under the replay mutes it.
- Uploading is best effort: a part that cannot be stored is retried for about two minutes; after that its segment ends, and what was stored before it still plays.
- When the prototype is ended, the page posts one message into the prototype’s frame, to the prototype’s origin:
{ "source": "userjourneys-interviewer", "type": "prototype_ending" }. The frame is hidden at once and stays loaded for 2 seconds more. On this message, stop the recorder and post the audio you are still holding straight away: anything posted within those 2 seconds is stored, anything later is lost. (The samesourcealso sendsreplay_resnapshot; ignore types you do not handle.)
Participant flow
A study can have its own full-screen flow: intro screens in place of the welcome, the study’s screener, a Get ready screen, and on the call a short story and then the task.participant_flow is null (the default flow) or an object, set through the studies_config_update MCP tool or uj studies config set <id> --file config.json. It is edited as JSON only; there is no editor in the app.
intro(1 to 8 screens) replaces the welcome. The first screen always shows the Terms line as its small print.getReady(optional,{ title?, points?, cta?, finePrint? }) rewords the Get ready screen, the last one before the call. Its microphone behaviour is fixed; a field left out keeps its default.story(0 to 10 screens, default none) shows on the call, before the task screen, when the task card would appear: withtask.checkUnderstandingabout 3 seconds after the interviewer’s introduction, otherwise with the prototype. WithstartOn: "agent"it waits for the interviewer’sPROTOTYPE_START; withtask.checkUnderstandingtoo, the story comes once the words the interviewer says with that call are spoken, and the prototype still comes after the check.- The task screen comes after the story and is built from
prototype_config.task, so the participant and the interviewer read the same words.textis the headline; withsteps, the headline issituation(ortext), the steps are bullet points andhintis the line under the headline.imageUrlis the picture (otherwise the ChatGPT mark). WithtimeLimitthe screen says a timer at the top shows the time left. Its button is “Start”.audioUrlis not used in this flow. The Task button over the prototype reopens the task screen only. task(optional,{ kicker?, title, body?, rows?, align?, cta?, finePrint? }) words the task screen instead: the label above the headline (default “Your task”;nullfor none), the headline, the line under it, rows (see below), the button (default “Start”, or “Next” whenafterTaskscreens follow) and small print (none if left out, so no clock line). The picture stays as built, except that rows take its place andalign: "top"drops it, with the words at the top. The interviewer is told the screen reads the headline, the line and the rows, in place ofprototype_config.task.text.afterTask(0 to 3 screens, default none) come after the task screen and before the prototype, for example how a bonus works. The last one’s button closes the briefing, as Start does; the Task button never shows them again. They may use{key}values.lookAgain(optional) offers a story picture once more, over the prototype, the first time the prototype posts the eventafterEvent(for examplepick_confirmed), and never again. The offer showsartheavily blurred with an eye and<seconds> secon it,offer.title,offer.body, the buttonoffer.ctaand the small buttonoffer.decline, which skips it for good. The picture itself follows forseconds(1 to 30, default 5, counted from when it has loaded) with a bar that drains and a countdown,reveal.titleandreveal.body, and no button. AtimeLimitclock stands still while either is up, so the look costs no time. The interviewer gets silent notes:look_offered, thenlook_shownorlook_skipped, and is told the picture comes back once by itself. Once it is over, atoastline, if set, is posted into the prototype’s frame as{ "source": "userjourneys-interviewer", "type": "toast", "text": "..." }.saveChat(optional,{ title, body?, cta, decline, finePrint?, shareTitle?, buy? }) offers, on the thank-you screen after the call, to save the prototype’s chat. The buttonctaopens the phone’s share sheet with the whole chat as text, titledshareTitle(defaulttitle), and the small buttondeclineturns it down. The offer shows only when the prototype posted its chat during the call, as{ "source": "<prototype>", "type": "chat_export", "text": "..." }(the latest one wins, up to 100,000 characters). The interviewer is told nothing about it.buy(optional,{ cta, unavailable }) turns the thank-you screen into a full-screen choice, withtitleandbodyat the top and three buttons that look alike: buying what they landed on, worded per study (for example “Go buy it now” or “Go switch now”), thenctaanddecline. Buying is a fake door: it buys nothing, its button goes away andunavailabletakes its place (for example “Sorry, that isn’t working right now. You can save the chat instead.”), and saving and declining stay. Saving or declining leads to the usual thank-you words, on a screen of their own. Each step is recorded on the session as aninterview_decision_eventsrow withkindparticipant_chat_save,actorparticipantandoutcomeoffered, thenbuy_tapped,saved,cancelled(they closed the share sheet),copied(no share sheet, so the chat was copied instead),failedordeclined, so the save rate per study iscount(distinct session_id) filter (where outcome = 'saved')over the sessions withoffered, and the buy rate the same withbuy_tapped. It cannot use{key}.saveLinks(optional,{ title, body?, cta, shareTitle? }) lists, on the thank-you screen after the call, the links the participant saved in the prototype. During the call links don’t open; a prototype that supports it (the ChatGPT relay’snew-chat-save-linksstart state) offers to save a tapped link or product for later instead, and posts the saved ones as{ "source": "<prototype>", "type": "links_export", "links": [{ "title": "...", "url": "https://..." }] }(the latest one wins; the first 50 links, http and https only). Each listed link opens in a new tab, and the buttonctahands the whole list to the phone’s share sheet as text, titledshareTitle(defaulttitle). The list shows only when they saved at least one, under thesaveChatoffer if there is one (not on the full-screen end choice ofsaveChat.buy). Each step is recorded on the session as aninterview_decision_eventsrow withkindparticipant_links_save,actorparticipantandoutcomeoffered,opened(they tapped a link in the list), thensaved,cancelled,copiedorfailed, with the number of links asdetail.links. It cannot use{key}.ratings(optional,{ kicker?, cta?, done?, items: [{ id, question, scale, low, high }] }) is an on-screen ratings form for when a fixed-length hands-on part (prototype_config.timeLimit) is over; without atimeLimitit is not shown. At the end of the time the page closes the app and shows each item on its own screen, with progress bars and Back, before the interviewer speaks: the small labelkicker(default “Rate the task”), thequestion, the scale withlowunder its left end andhighunder its right end, and the buttoncta(default “Next”), ordone(default “Done”) on the last one.scaleis"1-7"(seven numbered buttons, the Single Ease Question’s scale, so answers compare with published SEQ benchmarks) or"0-100"(NASA-TLX’s line of 21 marks in steps of 5, with no numbers). Nothing is chosen until they tap, every item needs an answer, and the low end is always on the left, so wordlowandhighso the direction is unmistakable (“Very difficult” / “Very easy”, “Very low” / “Very high”).id(lowercase letters, digits and underscores) names the item. While the form is up the call does not listen and the interviewer stays silent; it gets the silent noteratings_form=open, thenratings <id>=<value>/<top of scale> …,time_upand its turn, and is told each item’s question and ends so it can follow up on a rating where the study’s questions ask it to (“You rated frustration 80 out of 100. Walk me through when that happened.”). The answers are stored on the session as oneinterview_decision_eventsrow withkindparticipant_ratings,actorparticipant,outcomesubmitted, the values indetail.answersby id (detail->'answers'->>'ease') and each item’s words, scale and value indetail.items. 1 to 8 items; ids must be unique. It cannot use{key}.- A screen (
Screen) haslayout,titleandcta, and optionallybodyandart."info"screens can also havepoints(1 to 5) orrows(1 to 5, not both),kicker(a small label above the headline),artPlacement("above", the default, or"below"),alignandfinePrint. A screen with neither a picture nor rows has its words in the middle;align: "top"puts them at the top with the larger headline, as on a screen with rows (ignored with a picture)."story"screens needart: the picture runs edge to edge with the words under it. Texts are at most 400 characters, buttons 40. - A row (
{ title, body?, icon?, value?, tone? }) is one line of a rounded box under the headline:titlein bold,bodysmaller under it,icona tile on the left ("timer","pick", a tick, or"info", an “i” for a note),valuea short value on the right (at most 12 characters, e.g."+$2") andtone"highlight"(a tinted row, coloured value) or"muted"(grey). A screen with rows and no picture reads from the top, with a larger headline. artis a study image ({ "image": "WATCH_1", "alt": "..." }, an id fromuj studies screenshots create: JPG, PNG or WebP up to 4 MB), a link ({ "url": "https://...", "alt": "..." }, or a path on the app such as/interview-watch-story/party.webp), or a built-in graphic ({ "graphic": "chatgpt" | "app-icons" | "interviewer" | "watch-bonus" };"watch-bonus"is the hands-on time on a clock, three watch tiles from $0 to $2 with a lock on the middle one, and “Closer to his watch”, for a story screen). Study images the flow uses are left out of the images the interviewer can show. A missing image shows its failed state; whether an image id exists is not checked when the flow is saved.seenOnce: true(story screens only) marks a picture they see once. The first time, its button waits until the picture has loaded or failed to load. Back still works, but once they have moved past it the screen comes back blurred, with “You’ve already seen this” on it.holdSeconds(1 to 30, on story andafterTaskscreens and ontask) keeps the screen’s button off the first time for that many seconds, with the seconds left on the button (“Next (7)”). The count starts when the screen is up; on a story screen with a picture, when the picture has loaded or failed. After that, on a later visit, and on the task card reopened from the Task button, it works as usual. Intro screens can’t be held.variants(optional, 2 to 50 of{ id, values }) give each participant one set of values. Story screens and the task card (prototype_config.task) use a value as{key}, in words or in a picture ("url": "{photo}"). When the call starts the page asks the server for the session’s variant: it gets the one used least so far by the study’s real (non-test) sessions, at random between ties, and keeps it for the session, so a reload shows the same one. The sameparticipantIdlink param brings back the earliest photo still in the flow; a link withoutparticipantIdfalls back to the same browser. Each participant counts once per variant in the balance; test links reuse and balance among test sessions only. Questions and the clock start over on a new session. If the server cannot be reached within 8 seconds, the page picks one from the session id. The interviewer gets one note,[proto] variant=<id> item="running shoes", with the variant’s text values only (picture values are never sent), so question notes can refer tovariant=<id>. The interviewer is also told the story screens’ words, and never to describe a picture shown once.- When the flow is saved: every
{key}must exist in every variant and all variants have the same keys; intro, Get ready,saveChatandsaveLinkscannot use{key}(the variant is picked when the call starts), nor canratings; a key used in a picture cannot be used in words; story screens need a picture; image ids and links must have the right form.
Screener
A study can ask respondents a few multiple-choice questions before the interview, and let only the ones who qualify through.screener_questions is read with the studies_config_get MCP tool or uj studies config get <id> --json, and replaced with studies_config_update or uj studies config set <id> --file screener.json, where the file holds { "screener_questions": [...] } (a whole config get file works too).
- Up to 5 questions, each with 2 to 6 options, in the order shown. The app’s editor adds up to 3; a longer screener set here still shows there.
- The respondent picks one option per question. They go on to the interview only when every option they picked has
qualifies: true; anyone else lands on the deflect screen. - An update replaces the whole screener. A question or option sent with its
idfromconfig getis edited in place; one without anid(or with an id from another study) is added; a stored question or option left out is deleted.[]removes the screener. - A screener sent back unchanged (the same ids, words, flags and order) is not written, so applying a
config getfile with only other fields edited leaves it alone. textandlabelare in the study’s main language. When the study has more than one language, the screener is translated into each when it changes and whensupported_languageschanges; a translation that fails comes back as a warning (on stderr from the CLI) and the screener is still saved.