Skip to main content
A study is a research configuration: the questions, target audience, and settings for a set of interviews. Each study has a public interview link that you send to respondents.

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

string
required
Bearer token. See Authentication.
string
active (default), paused, concluded, or all. Filters on the stored status; a stale or limit-reached study is active.
integer
Number of studies to return. Default 20, max 100.
string
Cursor for pagination. Pass the id of the last study from the previous page.
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.
Cache this response for a few minutes. Study capacity doesn’t change often, and caching avoids unnecessary API calls.

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

string
required
Bearer token. See Authentication.
string
required
Study ID (UUID).
string
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.
Returns 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

string
Study ID (UUID).
string
"study"
string
Display name.
string
"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.
boolean
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.
object
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.
string[]
Language codes the study supports (e.g. ["en", "es"]).
object
string
ISO 8601 timestamp.
object
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 of GET /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.
object | null

Detail-only fields

These fields are only included in GET /v1/studies/:id responses:
string | null
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.
string | null
The research objective for this study.
string | null
The product being researched.
string | null
What the product is and does, as the interviewer and the Study Manager read it.
string | null
"existing_user" or "discovery".
string | null
Who is being interviewed, in the study owner’s words.
object[]
The interview questions.
integer
Total number of completed interviews for this study.
object | null
Interactive prototype the participant uses during the interview, or null when the study has none. See Interactive prototype.
object | null
The study’s own full-screen participant flow, or null for the default flow. See Participant flow.
object | null
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.
  • baseUrl must be https (http is allowed only for localhost). The prototype publishes its valid { screen, scenario } pairs at GET {baseUrl}/api/states.
  • description (max 240 characters) is what the interviewer agent reads about the start state.
  • prototype is the prototype’s id: every message the prototype posts carries it as source, and the participant page accepts no other. Copy it from GET {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 the screens array from GET {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 from GET {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 from GET {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. audioUrl is an https audio clip they can play from the card, or null for 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 when audioUrl is null. 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 receives task_card=opened and reference_played notes.
    • steps (optional, 1 to 4 strings of up to 120 characters) makes the card readable at a glance: it shows situation (optional, max 160 characters) as a short scenario line in small type, the steps big and numbered, and hint (optional, max 160 characters, e.g. “Start from the search bar.”) small and muted under them, in place of text, on the first card and when reopened. situation and hint are ignored without steps. text stays 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 without steps shows text as 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; see handOver for a longer check). Where the prototype would appear by itself after the introduction, the card appears on the call screen instead (the agent receives task_card=briefing) and the prototype stays hidden. Tapping Start closes the card and brings them back to the call; the agent receives task_card=started and, 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?”. With handOver: "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. (A PROTOTYPE_START from the agent after Start is held the same way.) With microphone the 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 call PROTOTYPE_START before the check. With startOn: "agent" the card waits for the agent instead: its PROTOTYPE_START brings 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 sends shown=start); with handOver: "agent" the prototype instead waits for the interviewer’s PROTOTYPE_START, as described under handOver. The Task button over the prototype works as usual. Off, nothing changes.
    • handOver (optional, "reply" or "agent", default "reply"; only with checkUnderstanding) 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 calls PROTOTYPE_START in 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_START is refused with a result that tells the agent to wait (with startOn: "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 the goal query 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 the minutes query 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=met ends the hands-on part at once (it calls PROTOTYPE_END before speaking, then follows the study’s instructions), goal=missed gets the miss sentence and nothing else, and time_up minutes=<n> ends the hands-on part. So the prototype must support it: decide what a try is, check each one against goal, and post those notes with turn: 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 calls PROTOTYPE_START at the moment the study’s instructions say, for example after a few opening questions, and the task card comes with the prototype. With task.checkUnderstanding, PROTOTYPE_START shows 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. minutes is 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 last settleSeconds (0 to 120, default 30; 0 for none) a red bar under the header says “Time’s almost up. Make your final choice.”, or settleText (up to 80 characters, e.g. “Say your pick out loud now.”) when the study sets it, and the interviewer receives settle seconds_left=<n>. At zero the page ends the hands-on part itself, sends time_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’s PROTOTYPE_END until 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 when goal is set, since a goal’s hands-on part ends when it is met. clock is "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, so settleSeconds and settleText are ignored, and there is no settle bar and no settle note.
  • activityKeepAlive (optional boolean, default off): when true, 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): when true, 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, with turn: true on a message (see Prototype messages), about a second after that note is delivered. A prototype that never sets turn leaves 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 with activityKeepAlive. 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): when true, 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 sends held: false, and the page answers held: false when 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 when microphone is true.
  • 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_START shows it, PROTOTYPE_END hides 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 to window.parent:
  • source must equal prototype_config.prototype; type is the prototype’s own event name; ts, seq and sessionId identify the message.
  • note (max 280 characters) is what the agent reads. events in the study config explains every note.
  • detail (optional, max 8,000 characters): the full text behind the note, for example a whole chatbot answer behind reply_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 an activity message, 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; activity sends nothing and only shows the participant is busy, so the agent is not told they are idle. A now message without a note reaches the agent as event=<type>.
  • merge: a key; a newer note with the same key replaces the pending one, e.g. typing sends typed=12 then typed=40 and the agent receives typed=40.
  • state: values that open every note, on=<screen> first (null removes a key).
  • turn (optional boolean, default off): true asks the page to give the interviewer a turn to act on this note. It only matters in a study with microphone: 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 an activity message. 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 told idle=<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.
In Conversation history each such note is a transcript line of its own, labelled Participant → app or with the study’s product name (App when the study has none), placed by time between the interviewer’s and participant’s turns. Clicking a line seeks the recording to it, and it is highlighted during playback like any other line. Nothing else in a note is treated as speech: every other note stays behaviour, summarised in the caption under a turn (or listed with Show prototype activity). Rules for the prototype:
  • 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 merge on 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 with turn: true is 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.
These lines appear in Conversation history only. The API, exports and the analysis of answers are unchanged.

Recording the participant’s voice during the task

In a study with microphone: 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 MediaRecorder started with a timeslice). Its parts, joined in part order, must be one playable file. Start a new segment, with the next segment number and part back at 0, 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 with segment it identifies the recording: a part that reuses a segment number with another startedAt or mime is 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 with audio/, be at most 80 characters, and use only lowercase letters, digits, spaces and / ; = . + - (so audio/webm;codecs=opus and audio/mp4, but no quotes or capitals).
  • data: an ArrayBuffer of 1 byte to 512 KiB. Send a part about every 4 seconds.
  • source, ts, seq and sessionId are 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_audio message is accepted only in a study with microphone: 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 same source also sends replay_resnapshot; ignore types you do not handle.)
This records the participant’s voice during the task. You are responsible for telling participants so before they start, for example in the study’s welcome text or the task card, and for having whatever consent your study needs.

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: with task.checkUnderstanding about 3 seconds after the interviewer’s introduction, otherwise with the prototype. With startOn: "agent" it waits for the interviewer’s PROTOTYPE_START; with task.checkUnderstanding too, 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. text is the headline; with steps, the headline is situation (or text), the steps are bullet points and hint is the line under the headline. imageUrl is the picture (otherwise the ChatGPT mark). With timeLimit the screen says a timer at the top shows the time left. Its button is “Start”. audioUrl is 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”; null for none), the headline, the line under it, rows (see below), the button (default “Start”, or “Next” when afterTask screens follow) and small print (none if left out, so no clock line). The picture stays as built, except that rows take its place and align: "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 of prototype_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 event afterEvent (for example pick_confirmed), and never again. The offer shows art heavily blurred with an eye and <seconds> sec on it, offer.title, offer.body, the button offer.cta and the small button offer.decline, which skips it for good. The picture itself follows for seconds (1 to 30, default 5, counted from when it has loaded) with a bar that drains and a countdown, reveal.title and reveal.body, and no button. A timeLimit clock stands still while either is up, so the look costs no time. The interviewer gets silent notes: look_offered, then look_shown or look_skipped, and is told the picture comes back once by itself. Once it is over, a toast line, 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 button cta opens the phone’s share sheet with the whole chat as text, titled shareTitle (default title), and the small button decline turns 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, with title and body at 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”), then cta and decline. Buying is a fake door: it buys nothing, its button goes away and unavailable takes 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 an interview_decision_events row with kind participant_chat_save, actor participant and outcome offered, then buy_tapped, saved, cancelled (they closed the share sheet), copied (no share sheet, so the chat was copied instead), failed or declined, so the save rate per study is count(distinct session_id) filter (where outcome = 'saved') over the sessions with offered, and the buy rate the same with buy_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’s new-chat-save-links start 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 button cta hands the whole list to the phone’s share sheet as text, titled shareTitle (default title). The list shows only when they saved at least one, under the saveChat offer if there is one (not on the full-screen end choice of saveChat.buy). Each step is recorded on the session as an interview_decision_events row with kind participant_links_save, actor participant and outcome offered, opened (they tapped a link in the list), then saved, cancelled, copied or failed, with the number of links as detail.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 a timeLimit it 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 label kicker (default “Rate the task”), the question, the scale with low under its left end and high under its right end, and the button cta (default “Next”), or done (default “Done”) on the last one. scale is "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 word low and high so 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 note ratings_form=open, then ratings <id>=<value>/<top of scale> …, time_up and 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 one interview_decision_events row with kind participant_ratings, actor participant, outcome submitted, the values in detail.answers by id (detail->'answers'->>'ease') and each item’s words, scale and value in detail.items. 1 to 8 items; ids must be unique. It cannot use {key}.
  • A screen (Screen) has layout, title and cta, and optionally body and art. "info" screens can also have points (1 to 5) or rows (1 to 5, not both), kicker (a small label above the headline), artPlacement ("above", the default, or "below"), align and finePrint. 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 need art: 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: title in bold, body smaller under it, icon a tile on the left ("timer", "pick", a tick, or "info", an “i” for a note), value a short value on the right (at most 12 characters, e.g. "+$2") and tone "highlight" (a tinted row, coloured value) or "muted" (grey). A screen with rows and no picture reads from the top, with a larger headline.
  • art is a study image ({ "image": "WATCH_1", "alt": "..." }, an id from uj 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 and afterTask screens and on task) 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 same participantId link param brings back the earliest photo still in the flow; a link without participantId falls 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 to variant=<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, saveChat and saveLinks cannot use {key} (the variant is picked when the call starts), nor can ratings; 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 id from config get is edited in place; one without an id (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 get file with only other fields edited leaves it alone.
  • text and label are in the study’s main language. When the study has more than one language, the screener is translated into each when it changes and when supported_languages changes; a translation that fails comes back as a warning (on stderr from the CLI) and the screener is still saved.