Studies

Ask a study question

Send a question to all minds in a study or a selected subset of attached audiences. Returns a Server-Sent Events stream with start, optional classification, per-mind answers, aggregation progress, final output data, and done events.

post/api/v1/studies/{studyId}/ask

Request

  • Base URL: https://api.getminds.ai
  • URL: https://api.getminds.ai/api/v1/studies/{studyId}/ask
  • Auth: HTTP bearer

Path parameters

studyIdstring uuid required

Study UUID.

Request body

questionstring required

Research question to ask the study.

sourcePolicy'auto' | 'knowledge_only'

knowledge_only forbids live/request sources, requires each Mind's processed knowledge, and fails closed when retrieval is empty.

historyMode'last5' | 'followup_only' | 'none'

How much of each Mind's own prior answers this question carries. Defaults to none. Use last5 when a respondent's coherence across items is the deliverable.

audienceIdsstring[]

Optional subset of attached audience UUIDs to ask. Defaults to all audiences on the study.

modelstring

Optional per-request model override. Must be sent together with provider.

provider'openai' | 'anthropic' | 'google'

Provider for the model override. Must be sent together with model.

disableQuestionClassifierboolean

Skip automatic scale/categorical/multiselect/qualitative classification.

responseMode'stream' | 'queued'

Use queued to persist the question and return immediately while durable workers generate the answers. Queued asks support sourcePolicy auto; use the durable runs endpoint for request_only, knowledge_only, or model connections. When omitted, the ask streams; while Minds of the Study are still training it is queued instead and answers 202 with the queued receipt (sourcePolicy auto). An explicit stream always streams, waiting with the stream open (up to 9 minutes) until those Minds are ready.

responseForm'concise' | 'standard' | 'expanded'

How long and how shaped each answer should be, for qualitative questions: concise one short message (5-20 words), standard 1-3 sentences (25-90 words), expanded 2-5 sentences (70-180 words). Omit to let the question decide, which is the existing behaviour. An authored form outranks the phrasing of the question, so a fixed instrument keeps its exact wording. Ignored for scale, categorical and multiselect questions, which are shaped by their answer space.

clientRequestIdstring uuid

Optional idempotency key for queued submissions.

Response

SSE stream of study generation events, or a durable queue receipt (JSON) when responseMode is queued. An explicit responseMode stream whose Minds are still training waits with the stream open: a minds_preparing event (waitingFor, retraining, waitedMs) per check, then the usual events; if they are not ready within 9 minutes it ends with an error event (409 PANEL_MINDS_NOT_READY, cause: minds_training, with the counts) and nothing is charged. Minds being retrained answer with their current version, so only brand-new Minds are waited for.

status'queued' | 'preparing' required

preparing while the run waits for Minds that are still training; it starts on its own once they are ready.

waitingForinteger

Minds the run waits for before it starts. Present only with status: preparing.

jobIdstring
countinteger required
questionBlockIdstring required

Canonical Question Block correlation ID.

questionAudienceIdstring

Legacy alias for questionBlockId.

clientRequestIdstring uuid required
queuedMessagetrue required

Changes

No recorded changes to this operation across all 1 revision of this API.