Study Runs

Create a durable study run

Atomically accepts a study question and returns a durable run that can be polled, replayed, or cancelled independently of the request connection.

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

Request

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

Path parameters

studyIdstring uuid required

Request body

questionstring required
clientRequestIdstring uuid

Stable idempotency key for safe retries.

audienceIdsstring[]

Optional subset of attached Audiences. Defaults to all Audiences in the Study.

attachmentsobject[]
linksobject[]
keywordsobject[]
sourcePolicy'auto' | 'knowledge_only'
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.

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

How much of each Mind's own prior answers this run carries. none (default) treats every question as an independent measurement and lets the run process questions in parallel. last5 gives each Mind its own five most recent answers, which costs roughly 2.4x wall-clock and buys ~0.6pp of accuracy. followup_only carries history for conversational turns but not questionnaire items.

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.

routeResearchBriefboolean

When true, a broad or generated research objective returns a reviewable planning_required response instead of being submitted verbatim to every respondent.

Response

Research planning is required; no run was accepted.

Changes

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